How to Test Mobile Money Payments in Sandbox (Uganda Developer Guide)

Both MTN MoMo and Airtel Money provide sandbox environments for developers. These sandboxes simulate the real payment flow without processing actual transactions or moving real money.

MoMo Sandbox Setup

1. Register on the MoMo Developer Portal (momodeveloper.mtn.com).
2. Subscribe to the Collections API product.
3. Provision a sandbox user: generate a UUID, POST to the provisioning endpoint, then create an API key.
4. You now have: a subscription key, an API User ID, and an API Key. These work only in the sandbox.

Airtel Money Sandbox Setup

Airtel Money's developer program provides sandbox credentials through their own portal. The process varies and may require contacting their developer support team.

Callback Testing Setup

For both providers, you need a publicly accessible URL to receive callbacks during development:

1. Install ngrok: npm install -g ngrok or download from ngrok.com
2. Start your local server (e.g., on port 3000)
3. Run: ngrok http 3000
4. Use the HTTPS URL ngrok provides as your callback URL

Note: the free ngrok URL changes every time you restart ngrok. If you are using a callback URL registered on the developer portal (not per-request), update it each time.

Most developers test the happy path and call it done. In production, the unhappy paths are where all the bugs hide. Here is the complete list of scenarios to test:

Success Scenarios

• Standard payment: request sent, customer confirms, callback received with SUCCESSFUL status
• Status polling: request sent, customer confirms, you poll the status endpoint and get SUCCESSFUL
• Both MoMo and Airtel Money (if you support both): test each provider separately

Failure Scenarios

• Insufficient balance: the customer does not have enough funds
• Wrong PIN: the customer enters an incorrect PIN (MoMo sandbox may auto-approve, so note this limitation)
• Transaction declined by the customer: the customer sees the prompt and actively declines
• Subscriber not found: the phone number is not registered for mobile money

Edge Case Scenarios

• Timeout: the customer never confirms (prompt expires). Verify your timeout handling works.
• Duplicate callback: your server receives the same callback twice. Verify idempotency.
• Missing callback: your callback endpoint is temporarily unreachable. Verify your polling fallback picks up the result.
• Concurrent payments: two payments for different orders happen at the same time. Verify they do not interfere with each other.

UI/UX Scenarios

• Verify the waiting state appears and is clear
• Verify the success screen shows the correct order details and amount
• Verify the failure screen shows a helpful message (not a raw error code)
• Verify the timeout screen offers a retry option

The MoMo sandbox is designed primarily for testing the happy path. Simulating failures requires some creativity:

Simulating Timeouts

Send a payment request but do not poll for the result immediately. Wait beyond your timeout period and verify your timeout logic triggers. Since the sandbox auto-approves, the callback will arrive as SUCCESSFUL, but your timeout logic should still work correctly (the frontend should have already shown the timeout message before the callback arrives).

Simulating Callback Failures

Stop your callback server after sending a payment request. The callback will fail to deliver. Verify that your polling mechanism picks up the payment result from the status endpoint.

Simulating Duplicate Callbacks

Manually send a duplicate callback to your callback endpoint (using curl or Postman with the same payload as a real callback). Verify that your handler processes it idempotently.

Simulating Invalid Phone Numbers

Send a payment request with a malformed phone number. Verify that the API returns an appropriate error and your app displays a useful message.

Testing with Aggregator Sandboxes

If you are using Flutterwave, EasyPay, or another aggregator, their sandboxes may offer richer failure simulation. Some aggregators provide test phone numbers that trigger specific failure scenarios (insufficient balance, declined, timeout). Check your aggregator's documentation for test numbers.

The sandbox is not identical to production. Be aware of these differences:

• No real USSD prompt: In sandbox, payments are auto-approved. You cannot test the actual customer experience of seeing the prompt on their phone and entering their PIN. You can only test this in production with real transactions.
• Timing differences: Sandbox callbacks arrive almost instantly. In production, callbacks may be delayed by network conditions, high load on the provider's side, or other factors. Your code must handle variable latency.
• Fee deductions: Sandbox transactions do not deduct fees. In production, the amount received in your merchant account is the amount charged minus the provider's transaction fee. Test with small real transactions in production to verify your reconciliation logic.
• Rate limits: Sandbox may have different (usually more lenient) rate limits than production. If your app sends many requests per second, you may hit production rate limits that you never saw in sandbox.
• Phone number validation: Sandbox may accept any phone number format. Production enforces stricter validation. Make sure your code formats phone numbers correctly before sending to the API.

Plan for a "soft launch" phase where you test in production with a small group of real users and small transaction amounts before opening to your full audience.

The transition checklist:

1. Apply for production credentials. Through the MoMo Developer Portal (and Airtel Money developer program). This involves a review process and business verification. Start early.
2. Update environment variables. Switch base URL, API keys, subscription key, and target environment from sandbox values to production values. If you structured your code with environment variables from the start, this is a config change.
3. Deploy your callback endpoint to production. No more ngrok. Your server must be deployed to a production environment with a real domain and SSL certificate.
4. Test with small real transactions. Send a payment for a small amount (a few hundred UGX) to verify everything works end-to-end with real money. Check that the money actually arrives in your merchant account.
5. Verify fee calculations. Confirm that the amount you receive matches what you expect after the provider's fees are deducted.
6. Monitor closely for the first week. Watch your logs for errors, failed callbacks, and unexpected states. Production always surfaces issues that sandbox did not.

For a detailed production deployment guide, McTaba's Deployment and Going Live course (KES 4,999, approximately UGX 140,000) covers the full production checklist including environment management, monitoring, and rollback strategies.