MTN Mobile Money API Tutorial for Beginners (Rwanda, 2027)

This tutorial assumes you have basic knowledge of JavaScript and Node.js. You should be comfortable creating a simple Express server and sending HTTP requests. If you are not there yet, complete the first five steps of our coding learning roadmap before attempting this tutorial.

You will need:

• Node.js installed on your computer (version 18 or later)
• A code editor (VS Code recommended)
• A terminal or command prompt
• An internet connection
• Optionally, ngrok or a similar tunneling tool for callback testing

This tutorial covers the sandbox environment only. For going live with real transactions, see our full MoMo integration guide.

Go to the MTN MoMo Developer Portal. Create an account with your email address. After verifying your email, log in and navigate to the API products section.

Subscribe to the Collections product. This is the API that lets you receive payments from customers. You will receive a primary key and secondary key for the sandbox environment. Save these. You will use them in every API call.

The sandbox environment is free and does not require any business verification. You can start building immediately.

Create a new project directory and initialize it:

mkdir momo-integration
cd momo-integration
npm init -y
npm install express axios dotenv

Create a .env file for your credentials:

MOMO_SUBSCRIPTION_KEY=your_primary_key_here
MOMO_API_BASE_URL=https://sandbox.momodeveloper.mtn.com
MOMO_CALLBACK_URL=https://your-ngrok-url.ngrok.io/callback
PORT=3000

Never commit your .env file to Git. Add it to .gitignore immediately. Leaking API credentials is one of the most common security mistakes developers make.

MoMo API authentication involves creating an API user and key in the sandbox, then using those to get an access token. The access token is what you include in every subsequent API call.

The sandbox authentication flow is:

1. Create an API user. POST to the sandbox provisioning endpoint with a reference ID (a UUID you generate) and your callback host.
2. Create an API key. POST to get a key for the user you just created.
3. Get an access token. Use Basic auth with your API user ID and API key to get a Bearer token.

In production, the API user and key are provided during the approval process. The sandbox requires you to create them programmatically.

This three-step authentication may feel complex compared to a simple API key. It is. Mobile money APIs handle real money, so the authentication is deliberately more secure. Once you have the access token, the rest of the integration is straightforward HTTP requests.

With your access token, you can now request a payment. This is the core of the Collections API.

You send a POST request with:

• Amount: The payment amount (e.g., "1000" for RWF 1,000)
• Currency: "RWF" for Rwandan Franc
• External ID: Your unique reference for this transaction
• Payer: The customer's phone number (MSISDN format)
• Payer message: What the customer sees on their phone
• Payee note: Your internal note for the transaction

In the sandbox, the payment is simulated. No real MoMo prompt appears on any phone. The sandbox automatically simulates the customer confirming the payment.

After sending the request, the API returns a 202 Accepted status. This means "I received your request, but the payment is not complete yet." The result comes via callback or polling. This asynchronous flow is the fundamental difference between mobile money and payment gateways like Stripe, where the result is immediate.

When the transaction completes (or fails), MoMo sends a POST request to your callback URL with the transaction result. Your server needs to:

1. Have a route that accepts POST requests at your callback path (e.g., /callback).
2. Parse the incoming JSON payload.
3. Verify the transaction reference matches one you initiated.
4. Update your application state based on the result (mark order as paid, send confirmation, etc.).
5. Respond with a 200 OK to acknowledge receipt.

The localhost problem: During development, your Express server runs on localhost:3000. MoMo cannot reach localhost. You need a tunneling tool like ngrok to create a public URL that forwards to your local server. Run ngrok http 3000 and use the generated URL as your callback URL in the API request.

This is the step where most beginners get stuck. If your callback is not receiving requests, check: Is your server running? Is ngrok active? Does your callback URL match exactly? Is your server responding with 200? Debug one variable at a time.

Callbacks can fail. Networks drop. Servers restart. You should always have a fallback: polling the transaction status endpoint with your reference ID. This returns the current status of the transaction regardless of whether the callback succeeded.

In a production application, implement both: process the callback when it arrives, and poll for status if the callback has not arrived within a reasonable timeout (30 to 60 seconds). This dual approach ensures you never miss a transaction result.

When your sandbox integration handles both callbacks and polling correctly, you have a solid MoMo integration. The remaining work is building it into your application's UI and business logic, then testing thoroughly before going to production.

This tutorial covered the basic sandbox flow. To build a production-ready integration, you also need:

• Error handling for every failure mode (network errors, insufficient funds, wrong PIN, timeout). See our guide to common MoMo API errors.
• Transaction logging and reconciliation.
• Security: validating callbacks, storing credentials safely, using HTTPS.
• Production approval from MTN.

If you want to learn mobile money integration in a structured, mentored format with all of these topics covered, McTaba's M-Pesa Integration course (KES 9,999, approximately RWF 100,000) teaches the complete pattern. The course uses M-Pesa and Airtel Money as the teaching platform, but the callback architecture, error handling, and production deployment process you learn transfers directly to MoMo. You learn the pattern once, then adapt it to whichever API your project needs.