MTN MoMo

Connect your MTN Mobile Money collection and disbursement accounts, and what to expect from MoMo.

RazPay works with your own MTN MoMo merchant accounts. MTN gives a merchant two separate products, each with its own login on MTN’s partner portal and its own credentials:

Account	Used for	Without it
Collection	Payments in, pre-approvals, invoices, payer messages, wallet checks, balance.	RazPay can’t collect. Required.
Disbursement	Payouts and refunds, and its own balance.	Payouts and refunds are unavailable. Everything else works.

What you need from each account

From each product’s portal login, MTN issues three values:

Subscription key: the Ocp-Apim-Subscription-Key for that product. Collection and Disbursement have different keys.
API user: a UUID created for that product.
API key: the secret generated for that API user.

You enter them yourself in the dashboard. Don’t send them to anyone, including us.

Connecting your accounts

An organisation admin connects the accounts in the dashboard, under Organization → Provider accounts. The page also shows the two values below that you register with MTN.

When you create each API user on the portal, MTN asks for a callback host. Use the one shown on the Provider accounts page (api.razpay.razonetix.com). MTN only sends results to that host over HTTPS. Without it, RazPay still resolves every payment by checking with MTN, just a little more slowly.

Allowlist RazPay's server for disbursements

MTN can restrict disbursements to known IP addresses. Ask your MTN account manager to allowlist the server IP shown on the Provider accounts page. Until then, payouts and refunds fail with the provider rejected this server for disbursements — the server's IP must be allowlisted with MTN.

Connect Collection, then Disbursement

On Provider accounts, choose Connect on each card. Pick the environment (Sandbox, or Production (Eswatini): https://proxy.momoapi.mtn.com with target environment mtnswaziland; both are editable for other MTN markets) and paste the API user, subscription key and API key. For Disbursement, also choose your payout method, transfer or deposit: whichever MTN enabled for you.

RazPay checks the keys with MTN straight away (it fetches a token and reads the balance) and shows Verified, or MTN’s reason if they were refused. Use Verify to check again any time.

Confirm what your contract includes

In production MTN enables only what your contract covers. Check with your account manager:

Transfer or deposit for payouts.
Pre-approvals and invoices, if you plan to use them.
Whether you’re set up as an aggregator. If so, enter the transfer type MTN gives you under Advanced when connecting.

Check it in the dashboard

Once connected, Payment Methods shows what your MoMo accounts can do, and the overview shows both balances.

To change keys, use Update (leave a key field empty to keep the stored one). Disconnect deletes the stored keys; payments through that account stop until it’s connected again.

How we protect your credentials

Encrypted in your browser. The keys are encrypted on your device before they’re sent, with a key whose private half only RazPay’s key management service holds. They never cross the network, our logs or our error tracking in readable form.
A key unique to your business. Stored keys are encrypted with a data key that belongs to your organisation alone, itself protected by a key management service. A copy of RazPay’s database on its own reveals nothing.
Never shown again. After you save them, nobody sees your keys again, Razonetix included. The dashboard shows only the API user and the last 4 characters of each key.
Only your calls use them. Every request your projects make uses your organisation’s own accounts, never another business’s.

How MoMo behaves

Approval window. Customers have about 5 minutes to approve a payment prompt before MoMo expires it.
Messages. Descriptions, notes and payer messages are limited to 160 characters and some symbols are rejected. RazPay trims and cleans them for you.
Currency. Use the currency of your MTN environment: SZL in Eswatini production. MTN’s sandbox only accepts EUR.
Numbers. Eswatini MoMo numbers are 8 digits starting with 76 or 78. RazPay accepts them with or without +268.
Results. MTN sends each result to RazPay once, with no retry. RazPay also checks every pending transaction, pre-approval and invoice in the background, so nothing depends on that one message arriving.
Undocumented failure codes. MTN sometimes returns failure codes it doesn’t document. RazPay passes them on in plain words. See Failure reasons.

Sandbox

MTN’s sandbox (sandbox.momodeveloper.mtn.com) exposes every product and operation, and provisions API users through its own API instead of the portal. It’s useful for testing an integration, but production only allows what your contract includes, so test the flows you need against production with small amounts before launch.