> ## 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

> Collection API de MTN Mobile Money — 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.

## Pays couverts

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

## URLs

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

## Credentials requis

À renseigner dans **Settings → Stores → MTN** :

| Champ                | Type     | Description                                                                                                 |
| -------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `sub_key_collection` | password | **Collection Subscription Key** — depuis votre dashboard MTN Developer, section *Collections subscription*. |
| `api_user`           | text     | UUID v4 généré via le portail (par ex. `11111111-2222-3333-8444-555555555555`).                             |
| `api_key`            | password | Généré **une seule fois** après création de l'API User. Non-récupérable.                                    |

## Particularités

* **Double authentification** : MTN exige à la fois la `Ocp-Apim-Subscription-Key` (en-tête) **et** un token OAuth bearer obtenu via `POST /collection/token/` en Basic auth (`api_user:api_key`).
* Token caché en mémoire avec marge de sécurité de 60 secondes avant expiration.
* L'en-tête `X-Target-Environment: sandbox` est obligatoire pour le mode sandbox.
* L'en-tête `X-Reference-Id` (UUID) doit être unique par requête — SandPay en génère un automatiquement.
* Les `msisdn` sont envoyés **sans le `+`** dans le payload (`partyId`).

## Codes d'erreur natifs mappés

Les codes natifs MTN sont traduits vers les statuts canoniques SandPay (`SUCCESS`, `PIN_INVALID`, `INSUFFICIENT_FUNDS`, `ACCOUNT_BLOCKED`, …). Consultez `frontend/lib/operators/_errors.ts` côté repo pour la table complète.

## Voir aussi

* [Scénarios](/fr/scenarios) — driver de résultat indépendant de l'opérateur
* [Orange](/fr/operators/orange), [Moov](/fr/operators/moov), [Airtel](/fr/operators/airtel)