Integrating Mobile Money into Your Web or Mobile App

If you are building a product for Ugandan consumers, you must support mobile money. A significant proportion of the population transacts entirely through MTN MoMo or Airtel Money — many do not hold traditional bank accounts at all. Ignoring mobile money means excluding a large portion of your potential market.

How Mobile Money APIs Work

Both MTN Mobile Money and Airtel Money expose REST APIs that allow you to:

• Request to Pay (Collections) — prompt a user's phone to authorise a payment to your business
• Transfer (Disbursements) — send money from your business wallet to a user's mobile money account
• Check Balance — query your business wallet balance
• Transaction Status — check whether a payment has been completed

The typical Collections flow works as follows: your backend initiates a payment request via the API, specifying the user's phone number and the amount. The user receives a USSD push notification prompting them to enter their PIN. Once they approve, your backend receives a callback confirming success.

The Sandbox Environment

MTN MoMo provides a sandbox environment for development and testing. You can obtain sandbox API credentials from the MTN MoMo Developer Portal. Airtel Money also provides a sandbox through their developer portal.

Always develop and test in the sandbox first. Both APIs use OAuth 2.0 for authentication, so you will need to implement the token refresh flow correctly before going to production.

Key Integration Considerations

Idempotency

Mobile money payments are asynchronous. A user may click "Pay" multiple times due to a slow connection, or your server may retry a failed request. Each API request must include a unique X-Reference-Id (UUID) that the provider uses to deduplicate requests. Store this reference ID in your database before initiating the payment, and use it to check status if you do not receive a callback.

Webhooks vs Polling

Both providers support callback URLs (webhooks). Register a publicly accessible HTTPS endpoint and handle the callback to mark a transaction as complete. As a fallback, implement a polling mechanism that checks transaction status every 10–15 seconds for up to two minutes.

Phone Number Formatting

MTN Uganda numbers must be formatted as 256XXXXXXXXX (country code without the leading +). Strip any spaces, dashes, or leading zeros from user input and prepend 256. Validate the network prefix (MTN prefixes: 077, 078; Airtel prefixes: 070, 075) to route the request to the correct provider.

Production Checklist

• Store API credentials securely in environment variables — never in code
• Implement idempotent payment initiation
• Handle both webhook callbacks and polling fallback
• Log every transaction with its reference ID, amount, status, and timestamp
• Implement a reconciliation job that flags unresolved transactions after 30 minutes
• Test edge cases: user rejects the USSD prompt, insufficient balance, network timeout

Mobile money integration is one of our core competencies at Kazi Media. We have implemented it for e-commerce platforms, hospital payment systems, and SaaS subscription billing. If you need help getting it right, reach out — we are happy to help.