---
title: MTN MoMo
description: 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.

1. **Register RazPay's callback host**

    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.

2. **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`.

3. **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.

4. **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.

5. **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](/docs/concepts/errors#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.