> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sandpay.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MTN MoMo

> MTN Mobile Money Collection API — sandbox momodeveloper.mtn.com

<div style={{ display: "inline-block", width: "1rem", height: "1rem", background: "#B0900E", borderRadius: "2px", marginRight: "0.5rem", verticalAlign: "middle" }} />

**MTN MoMo** — Collection API.

## Covered countries

| Country       | Code | Currency |
| ------------- | ---- | -------- |
| Côte d'Ivoire | CI   | XOF      |
| Bénin         | BJ   | XOF      |
| Togo          | TG   | XOF      |
| Rwanda        | RW   | RWF      |

## URLs

| Type        | URL                                                    |
| ----------- | ------------------------------------------------------ |
| Dev portal  | [momodeveloper.mtn.com](https://momodeveloper.mtn.com) |
| Sandbox API | `https://sandbox.momodeveloper.mtn.com`                |
| USSD client | `*133#`                                                |

## Required credentials

Enter these in **Settings → Stores → MTN**:

| Field                | Type     | Description                                                                                            |
| -------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `sub_key_collection` | password | **Collection Subscription Key** — from your MTN Developer dashboard, under *Collections subscription*. |
| `api_user`           | text     | UUID v4 generated via the portal (e.g. `11111111-2222-3333-8444-555555555555`).                        |
| `api_key`            | password | Generated **once** after creating the API User. Non-recoverable.                                       |

## Specifics

* **Dual authentication**: MTN requires both the `Ocp-Apim-Subscription-Key` header **and** an OAuth bearer token obtained via `POST /collection/token/` using Basic auth (`api_user:api_key`).
* The token is cached in memory with a 60-second safety margin before expiry.
* The `X-Target-Environment: sandbox` header is required in sandbox mode.
* The `X-Reference-Id` header (UUID) must be unique per request — SandPay generates one automatically.
* `msisdn` values are sent **without the `+`** in the payload (`partyId`).

## Native error codes mapped

Native MTN error codes are translated to canonical SandPay statuses (`SUCCESS`, `PIN_INVALID`, `INSUFFICIENT_FUNDS`, `ACCOUNT_BLOCKED`, …). See `frontend/lib/operators/_errors.ts` in the repo for the full mapping table.

## See also

* [Scenarios](/en/scenarios) — result driver independent of the operator
* [Orange](/en/operators/orange), [Moov](/en/operators/moov), [Airtel](/en/operators/airtel)