MTN Mobile Money (MoMo)

MTN Mobile Money (MoMo)

MTN_MOMO collects through MTN’s MoMo Collections API. Centipid sends a RequestToPay to the subscriber’s MoMo number, the subscriber approves it on their handset, and Centipid verifies the result directly with MTN before recording the payment or restoring service.

The gateway catalog offers MTN MoMo in Uganda, Ghana, Côte d’Ivoire, Zambia, Benin, and Cameroon.

Before you start

Your MTN account must be approved for the Collections product in the target market. Obtain these values from MTN:

Value	Settings field
Collections subscription key	Collections subscription key
API user UUID	API user
API key issued for that user	API key

The API user’s registered callback host must match the hostname shown on the Centipid gateway page. Production activation, credentials, settlement currency, and commercial approval are handled by the MTN operation in each country.

Connect MTN MoMo

1. Open the gateway

   Go to Settings → Payments → MTN Mobile Money (MoMo).

2. Confirm the callback host

   Copy the displayed callback URL when MTN asks for it. The callback host must be your current Centipid workspace hostname.

3. Enter the credentials

   Enter the Collections subscription key, API user, and API key, then save. The subscription key and API key are handled as secret inputs.

4. Connect the gateway

   Complete the payment-gateway change verification and connect MTN MoMo.

How settlement works

1. Centipid saves the checkout reference and subscriber/package context before sending RequestToPay.
2. MTN returns 202 Accepted and prompts the subscriber’s handset.
3. MTN may call the workspace callback URL. Because that callback is unsigned, Centipid treats it only as a signal to query MTN.
4. A background job polls MTN independently, so settlement still completes when the callback is missed or the payer closes the browser.
5. Successful status creates one checkout-keyed payment and runs the normal exactly-once subscriber provisioning pipeline.

The captive payment screen also performs a throttled verified status query after the callback has been silent, so cancellation or failure can be shown promptly.

Sandbox and production

Environment	API host	Target environment	Currency
Sandbox / non-production	https://sandbox.momodeveloper.mtn.com	sandbox	EUR (required by MTN sandbox)
Production	https://proxy.momoapi.mtn.com	Country-specific MTN environment	Your country’s MTN settlement currency

Sandbox payments use MTN’s published test numbers and outcomes. Never use a real subscriber wallet as a sandbox fixture.

Troubleshooting

Symptom	What it means	What to do
Credentials are required when connecting	One or more Collections credentials are missing.	Re-enter all three values from the same MTN API user/subscription.
“Unable to authenticate with MTN Mobile Money…”	MTN rejected the subscription key, API user, or API key.	Confirm the product subscription and rotate the API key if necessary.
Request remains pending	The handset has not approved yet, MTN has not reached a terminal state, or MTN is temporarily unreachable.	Check the subscriber handset, then allow the built-in polling window to finish before initiating another request.
Callback does not arrive	MTN could not reach the registered host, or callback delivery was missed.	Confirm the API user’s callback host. Background polling still verifies settlement.
Production returns resource-not-found or access-denied	Sandbox credentials or the wrong country product are being used against production.	Ask the relevant MTN operation to confirm production activation and credentials.

Caution

Do not advise a payer to retry while the first request is still pending. An ambiguous network response can still represent an accepted RequestToPay; the saved reference and background query are the safe way to determine its result.