In Uganda, Mobile Money is how most people pay. If your app, online shop or school portal only accepts cards, you are shutting out a large share of customers. The good news is that you can accept MTN MoMo and Airtel Money directly in your product. This guide explains how to integrate a Mobile Money API into your app, step by step, covering the two main routes, the typical payment flow, testing, security and going live. It is written for developers and technical founders, but business owners will also find it useful for understanding what their developers need.
Two ways to accept Mobile Money
Option 1: Integrate directly with the network
MTN offers the MoMo Developer portal with APIs for collections (receiving payments), disbursements (sending money out) and remittances. Airtel Africa also runs a developer portal with APIs for collections and disbursements in the markets it serves, including Uganda. Direct integration usually gives you more control and potentially lower fees, but you integrate and maintain each network separately, and going live requires a business agreement and approval from each operator.
Option 2: Use a payment aggregator
Payment aggregators and gateways, such as Flutterwave, Pesapal and several Ugandan payment companies, offer a single API that supports MTN, Airtel and often cards too. You integrate once and the aggregator handles connections to each network. This is faster to launch and simpler to maintain, but the aggregator charges a fee per transaction and you depend on their uptime and support.
For most startups and small businesses, an aggregator is the quicker path. Larger companies with high volumes often go direct. Compare fees, settlement times and support before choosing, and confirm current rates with each provider.
How a typical Mobile Money payment flow works
Most Mobile Money collection APIs follow a "request to pay" pattern:
- The customer chooses Mobile Money at checkout and enters their phone number.
- Your server sends a payment request to the API with the amount, currency (UGX), phone number and your own unique reference.
- The network sends a prompt to the customer's phone asking them to approve the payment with their PIN.
- The customer approves or declines.
- The API notifies your server through a callback URL, or you check the status by polling with your reference.
- Your system marks the order as paid and shows a confirmation.
Important: never mark an order as paid just because the request was sent. Only confirm it when the API reports a successful transaction.
Step by step integration
Step 1: Register on the developer portal
Create an account on the MTN MoMo Developer portal, the Airtel developer portal or your chosen aggregator. Subscribe to the product you need, usually collections. You will receive credentials such as a subscription key, API user and API key, or client ID and secret, depending on the provider.
Step 2: Work in the sandbox first
Every provider offers a sandbox, a test environment where no real money moves. Use test phone numbers and test credentials from the documentation to simulate successful, failed and pending payments. Build your whole flow here before touching production.
Step 3: Get an access token
Most APIs use OAuth style authentication. Your server sends its credentials to a token endpoint and receives an access token, valid for a limited time. Include that token in the header of each payment request. Cache it and refresh it before it expires rather than requesting a new one every time.
Step 4: Send the payment request
Create a request containing the amount, currency, the payer's phone number in international format (starting with 256), a unique reference for the transaction and a short message the customer will see. Generate a unique ID for each attempt so you can track it and avoid duplicate charges.
Step 5: Handle callbacks and status checks
Set up a secure callback endpoint on your server that the provider can reach over HTTPS. When a payment completes, the provider sends the result there. Verify that the callback is genuine, following the provider's guidance on signatures or tokens, and check the transaction status through the API before updating your database. Also run a scheduled job that checks any payments still marked as pending, because callbacks can fail or be delayed.
Step 6: Show clear messages to the customer
Customers can get confused while waiting for the PIN prompt. Show a message like "Check your phone and enter your Mobile Money PIN to approve UGX 45,000." Offer a "Retry" button if the prompt times out, and explain what to do if money is deducted but the order does not update.
Security best practices
- Keep API keys and secrets on the server, never in mobile app code or front end JavaScript.
- Store credentials in environment variables or a secrets manager, not in your code repository.
- Use HTTPS everywhere, including your callback URL.
- Validate amounts on the server; never trust a price sent from the browser or app.
- Log every request and response with timestamps for reconciliation and disputes, but do not log PINs or full secrets.
- Protect against duplicate submissions with unique references.
- Restrict who on your team can access production credentials.
Going live
To move from sandbox to production, providers usually require business registration documents, such as a certificate of incorporation from URSB, a TIN from URA, director identification and details of your product. There may be a review of your integration and a test transaction. Once approved, you receive production credentials and endpoints. Start with small real transactions, check that money arrives in your account as expected, and set up a daily reconciliation between your records and the provider's statements.
Hosting your integration
Your payment backend needs reliable hosting with HTTPS, a stable public URL for callbacks, accurate server time and good uptime. Payment callbacks that hit a server which is down can leave orders stuck. A provider with LiteSpeed servers, free SSL, daily backups and responsive local support, such as Baasa Cloud, gives you a solid base for a payment enabled website or API.
Frequently asked questions
Can I accept Mobile Money on a WordPress or WooCommerce site?
Yes. Many aggregators provide WooCommerce plugins, so you can accept MTN and Airtel payments without writing the integration from scratch.
How long does it take to go live?
Sandbox integration can take days to a few weeks depending on complexity. Business approval timelines vary by provider, so start the paperwork early.
What fees should I expect?
Fees depend on the provider, transaction size and your agreement. Ask each provider for their current pricing and settlement terms.
Conclusion
Integrating a Mobile Money API into your app opens your product to millions of Ugandan users. Choose between direct integration and an aggregator, build and test in the sandbox, handle callbacks carefully, protect your credentials and reconcile daily. Do that, and Mobile Money payments will become one of the most reliable parts of your business.