How to Integrate MTN MoMo API in Uganda: A Developer's Guide

MTN Mobile Money handles the majority of Uganda's digital payments. When a business in Kampala, Gulu, or Mbarara needs to accept payments online, MoMo is the default. When a customer wants to pay for something digitally, they open their MoMo menu. The developer who can wire up that payment flow is the developer who gets hired and who keeps getting hired.

Despite this, almost no mainstream coding course teaches MoMo integration. Udemy teaches Stripe. YouTube tutorials teach PayPal. freeCodeCamp covers generic payment concepts. None of them teach the callback architecture, the sandbox environment, or the specific patterns that mobile money APIs in East Africa use. That gap between what courses teach and what Ugandan clients pay for is your opportunity.

The good news: if you understand one mobile money API, you understand the pattern behind all of them. The MTN MoMo API, the Safaricom M-Pesa Daraja API, and the Airtel Money API all follow the same fundamental architecture. Request, prompt, confirm, callback. The specifics differ (endpoints, authentication methods, parameter names), but the structure is the same. McTaba teaches this pattern using M-Pesa and Airtel Money, and the knowledge transfers directly to MoMo.

Before touching any code, understand the flow. Every MoMo payment follows this sequence:

1. Your app sends a payment request to MoMo. This is an HTTP POST to the MoMo API with the customer's phone number and the amount in UGX.
2. MoMo sends a USSD prompt to the customer's phone. The customer sees a pop-up asking them to confirm the payment by entering their MoMo PIN.
3. The customer confirms (or declines). This happens on their phone, outside your application. You do not control this step.
4. MoMo sends a callback to your server. A POST request to a URL you specified, containing the transaction result: success, failure, or timeout.
5. Your app updates based on the callback. Mark the order as paid, deliver the product, send a confirmation, whatever your business logic requires.

This is a request-callback pattern (sometimes called a webhook pattern). It is fundamentally different from Stripe or PayPal, where the payment happens in the browser and the result is available immediately. With MoMo, there is a delay between your request and the result because the customer has to interact with their phone. Your application needs to handle this asynchronous flow. Show a waiting state. Poll for status if the callback is delayed. Do not assume instant success.

This same architecture applies to M-Pesa (via STK Push) and Airtel Money Uganda. If you have used either, MoMo will feel familiar. If this is your first mobile money integration, learning this pattern once prepares you for all three providers.

MTN provides a developer portal and sandbox environment for testing. Here is how to get set up.

1. Create a developer account on the MTN MoMo Developer Portal (momodeveloper.mtn.com).
2. Subscribe to the APIs you need. For most applications, you want the Collections API (to receive payments). If you also need to send money to users, add the Disbursements API.
3. Generate sandbox credentials. The portal provides API keys and a sandbox user ID for testing. These credentials only work in the sandbox environment, not in production.
4. Set up your development environment. You need a server that can send HTTP requests and receive callbacks. Node.js with Express is the most common setup for JavaScript developers. Python with Flask or Django works equally well.

The sandbox simulates the full payment flow without moving real money. You can test payment requests, callback handling, and error scenarios safely. Do all your development and testing here before applying for production access.

Important: the MoMo API is the same across MTN's markets (Uganda, Rwanda, Ghana, etc.), but the production credentials and approval process are country-specific. Your Uganda sandbox credentials will not work for Rwanda or Ghana production environments.

For a detailed, step-by-step walkthrough with code examples, read our MoMo API tutorial for beginners.

The Collections API is what you use when a customer pays you. In MoMo terminology, this is a "Request to Pay" (sometimes called C2B, consumer-to-business). This is the API most Ugandan developers integrate first, because most projects start with accepting payments.

The basic flow in code:

1. Authenticate. Get an access token using your API key and secret. Tokens expire, so your code needs to handle token refresh.
2. Send a Request to Pay. POST to the Collections endpoint with the customer's MSISDN (phone number in the format 256XXXXXXXXX), the amount, the currency (UGX), and a unique reference ID (UUID v4) for the transaction.
3. Handle the callback. MoMo will POST the transaction result to your callback URL. Your server must be publicly accessible (not localhost) to receive this. During development, tools like ngrok can expose your local server to the internet.
4. Verify the transaction status. As a fallback, you can also poll the transaction status endpoint using the reference ID. This is useful if your callback endpoint misses a notification.

The Disbursements API lets you send money from your account to a customer's MoMo wallet. Use cases: refunds, payouts, cashback, salary disbursements, marketplace seller payments. The flow is simpler because there is no customer confirmation step. You send a disbursement request with the recipient's phone number and amount, and MoMo processes it. A callback confirms the result.

Disbursements carry more risk because you are sending real money out. Production access for disbursements typically requires a more thorough review from MTN Uganda.

For the specific error codes and how to handle them, see our guide on common MoMo and Airtel Money API errors.

If you are learning MoMo API integration, you are simultaneously learning a pattern that works across African mobile money platforms:

• Airtel Money (Uganda): Uganda's second major mobile money provider. Same request-callback architecture. Different API structure, but identical concepts. Many Ugandan apps integrate both MoMo and Airtel Money.
• M-Pesa (Kenya): Uses STK Push for collections. Same request-callback architecture. Different endpoint URLs and authentication method (OAuth vs. API key), but identical flow.
• Payment aggregators (Flutterwave, EasyPay, Beyonic, Yo! Uganda): These abstract multiple mobile money providers behind a single API. The underlying pattern is still request-callback.

This is why McTaba teaches mobile money integration as a pattern, not as a single API tutorial. Our M-Pesa Integration course (KES 9,999, approximately UGX 280,000) covers the architecture, the callback model, the sandbox workflow, and the production deployment process. The course teaches M-Pesa and Airtel Money explicitly. What you learn there applies directly to MoMo. The API endpoints are different. The architecture is the same.

To be clear: the M-Pesa course does not teach the MoMo API specifically. It teaches the request-callback pattern, authentication flows, error handling, and production deployment using M-Pesa as the vehicle. That pattern is what transfers to MoMo and every other mobile money API you will encounter.

Once your integration works in the sandbox, going live requires several steps:

1. Apply for production credentials. This is done through the MoMo Developer Portal. MTN Uganda reviews your application and your use case.
2. Complete any required KYC or business verification. MTN needs to verify your business before allowing real money transactions through your application. In Uganda, this may involve coordination with your business registration.
3. Switch your API endpoints and credentials. Production endpoints are different from sandbox endpoints. Update your configuration without touching your core integration code. Use environment variables.
4. Test in production with small amounts. Even after going live, start with small test transactions (a few hundred UGX) to confirm everything works with real money before processing large volumes.

The production approval process takes time. Start it early, not on the day before your launch. For detailed guidance, see our guide on testing mobile money payments in sandbox and our Deployment and Going Live course (KES 4,999, approximately UGX 140,000).