MTN MoMo API: how a website in Rwanda takes Mobile Money

What happens when a customer pays

1. The customer chooses MTN MoMo at checkout and enters their MTN number.
2. Your website’s server sends MTN a request to pay for the order amount, with a unique reference.
3. The customer receives a prompt on their phone and approves it with their MoMo PIN. Your website never sees the PIN.
4. MTN updates the payment to SUCCESSFUL or FAILED.
5. Your server confirms that result with MTN, then marks the order paid and sends the confirmation.

In the MTN developer documentation this is the Collections product and its request to pay operation. Everything in this guide follows from one rule: the order is paid when MTN says so, not when the customer’s browser returns to a thank you page.

What you need before writing code

Test in the sandbox first

The sandbox lets you run the whole flow without real money. MTN’s documentation sets out three details worth knowing before you start:

• The target environment for testing is sandbox. Live payments use the environment MTN gives you for Rwanda.
• The sandbox currency is EUR. Live payments in Rwanda are in Rwandan francs (RWF), so make sure the currency is a setting, not hard coded.
• MTN publishes test numbers that return specific failures, such as an account not found or a service that is unavailable. Any other number returns success.

That last point matters. If you only test with your own number, every payment will succeed and the failure paths will never run. Use MTN’s test numbers to check what the customer sees when a payment fails, and what happens to the order.

Callbacks and status checks

There are two ways to learn the result of a payment. Your server can ask MTN for the status of a request, or MTN can call your callback address when the status changes. To receive a callback, the request includes your callback URL, and that URL must use HTTPS.

MTN’s documentation is clear that the callback is sent only once, with no retry if your server misses it, and recommends checking the status as a fallback. So build both:

• Listen for the callback, but treat it as a signal to check, not as proof.
• Ask MTN for the status before marking the order paid, and confirm the amount and reference match the order.
• Check payments that stay pending after a few minutes, so a missed callback never leaves a paid customer waiting.
• Process each reference once. A repeated callback must not create a second order or a second delivery.

The WooCommerce Mobile Money checklist covers order states and the awkward cases to test before launch.

Keep it secure

• Keep the API key and subscription key on the server. Never put them in browser code, a theme file anyone can download, or a public code repository.
• Create a new reference for each payment attempt and store it with the order.
• Check the phone number before sending the request. MTN Rwanda numbers begin with 078 or 079.
• Log each request and result without storing more personal data than you need.
• Show the customer a clear message while the payment is pending, and a way to try again if it fails.

Where Airtel Money fits

Many customers in Rwanda pay with Airtel Money instead. Airtel has its own developer API with separate onboarding and credentials, so supporting both networks means two integrations, or one payment provider that combines them. Compare the three routes in the plugin, provider or custom integration table.

Building it into WordPress

On a WooCommerce shop, a payment integration is usually a plugin. Triad built WeConfirm Pay, which checks MTN MoMo and Airtel Money payments for WooCommerce stores, and builds custom WordPress plugins when a shop needs its own payment workflow.

If you are planning an online shop, start with the ecommerce service or send Triad your brief.