MTN Mobile Money API Integration Guide

Most tutorials stop at Paystack. This field guide covers MTN MoMo sandbox setup, webhook quirks, and the real production failure modes African developers face but rarely document.

MTN Mobile Money processes billions of cedis, naira, and francs every month across Africa. Yet ask any developer in Accra or Lagos about MoMo integration documentation and you will get a pained look. The official docs exist, but the gap between "sandbox passing" and "production working" is wide enough to swallow a sprint.

This guide closes that gap — sandbox to production, including the failure modes nobody writes about.

Understanding the MoMo API Architecture

MTN MoMo exposes its platform through the MoMo Open API, which is partitioned into distinct product collections:

Collections — request payment from a customer (consumer-initiated)
Disbursements — push money to a recipient (business-initiated)
Remittances — cross-border transfers
Sandbox — a simulated environment that mirrors the above products

Each product has its own API user, API key, and subscription key. This is the first place developers trip up: they generate one set of credentials and expect it to work across all products. It does not. Treat each product as an isolated service.

Sandbox Setup, Step by Step

Start at the MTN MoMo Developer Portal. The flow is:

Register and subscribe to the product you need (e.g., Collections).
Note your Ocp-Apim-Subscription-Key from the portal — this is your primary credential at the gateway level.
Create an API User by calling POST /v1_0/apiuser with a X-Reference-Id header (a UUID you generate) and a callback host in the body.
Generate an API Key by calling POST /v1_0/apiuser/{X-Reference-Id}/apikey.
Exchange those credentials for a Bearer token via POST /token/.

# Step 3 — Create API User (sandbox)
curl -X POST https://sandbox.momodeveloper.mtn.com/v1_0/apiuser \
  -H "X-Reference-Id: <your-uuid>" \
  -H "Ocp-Apim-Subscription-Key: <your-sub-key>" \
  -H "Content-Type: application/json" \
  -d '{"providerCallbackHost": "https://your-callback-host.com"}'

# Step 5 — Get Bearer Token
curl -X POST https://sandbox.momodeveloper.mtn.com/collection/token/ \
  -H "Ocp-Apim-Subscription-Key: <your-sub-key>" \
  -u "<api-user-id>:<api-key>"

The token expires in 3600 seconds. Cache it, do not fetch it on every request — you will hit rate limits fast under load.

Making a Collections Request

Once you have a valid token, trigger a payment request with POST /collection/v1_0/requesttopay. The key fields:

amount — string, not integer. "50.00" not 50.
currency — must match the operator's configured currency for that environment. In Ghana sandbox, use EUR (yes, really — sandbox currencies differ from production).
externalId — your internal transaction reference. Make it idempotent.
payer.partyIdType — always MSISDN.
payer.partyId — the phone number in international format, no +. For Ghana: 233XXXXXXXXX.

The API returns 202 Accepted immediately. This is not confirmation of payment. It means the request was queued. You must poll or listen via webhook to know the final status.

Webhook Quirks That Will Bite You

Delivery is not guaranteed in order

MTN MoMo webhooks can arrive out of sequence or be retried multiple times. A SUCCESSFUL callback can arrive before a PENDING one, or you may receive the same SUCCESSFUL event twice. Build your callback handler to be idempotent — check your database for the financialTransactionId before writing any state change.

Sandbox webhooks require a publicly reachable URL

localhost will not work. Use ngrok or a cloud-hosted staging environment during development. Many developers waste days wondering why callbacks never arrive — it is almost always a non-routable callback host.

Signature verification is absent by default

Unlike Stripe or Paystack, MTN MoMo does not sign its webhook payloads out of the box. In production, anyone who knows your callback URL can POST fake events to it. Mitigate this by:

Whitelisting MTN's IP ranges at your firewall or load balancer.
Treating callbacks as notifications only — always confirm status via GET /collection/v1_0/requesttopay/{referenceId} before crediting a user.

Real Production Failure Modes

1. "PAYER_NOT_FOUND" on valid numbers

This usually means the number is not registered on MTN's MoMo service, even if it is an active MTN SIM. In Ghana, a large portion of MTN subscribers have not activated MoMo wallets. Implement a pre-check UX step asking users to confirm their wallet is active.

2. Timeouts with no final status

The request-to-pay flow can hang in PENDING indefinitely if the subscriber's phone is off or they ignore the USSD prompt. Set a polling ceiling — after 5 minutes with no resolution, expire the transaction on your side and surface a retry option to the user.

3. Currency mismatch errors in production

Sandbox uses EUR. Production uses local currency codes: GHS for Ghana, NGN for Nigeria, UGX for Uganda. This switch has broken more than a few production go-lives. Make currency code an environment variable, not a hardcoded constant.

4. Subscription key rotation breaking live traffic

The developer portal allows key regeneration. If anyone on your team regenerates a key without updating the deployed environment variables, every MoMo call silently fails. Treat subscription keys like production database credentials — restricted access, rotation logged.

Structuring Your Integration Layer

Do not scatter MoMo API calls across your codebase. Wrap everything in a dedicated payment service:

A provider abstraction so you can swap or add Hubtel, Paystack, or Flutterwave without rewriting business logic.
A transaction log table that captures referenceId, externalId, status, providerStatus, and updatedAt — your audit trail when disputes arise.
A reconciliation job that polls for PENDING transactions older than 3 minutes, resolving or expiring them automatically.

This architecture pays dividends the moment you scale beyond Ghana or need to support multiple MNOs.

Why This Matters for Your Project

Mobile money is not a nice-to-have in African SaaS — it is often the primary payment rail your users trust. Getting the integration right from the start means fewer failed transactions, less customer support overhead, and a checkout experience that does not make users abandon. If you are building a fintech product, an e-commerce platform, or any SaaS with local monetisation in West or East Africa, a robust MoMo integration is a genuine competitive moat. The developers who understand the full failure surface are the ones whose products stay online when it counts.