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 |
| 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-Keyheader and an OAuth bearer token obtained viaPOST /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: sandboxheader is required in sandbox mode. - The
X-Reference-Idheader (UUID) must be unique per request — SandPay generates one automatically. msisdnvalues 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.