MobileWalletPartner Gateway Docs
API referenceMomo

Pay a customer (MoMo withdrawal)

Sends money from your balance to a customer's MoMo wallet. Must be signed (X-Timestamp, X-Signature). Refused with 400 if your balance can't cover it. The final status arrives by webhook or polling.

Sandbox: pick the outcome to rehearse

Click an outcome to copy its test number, then paste it as the msisdn below. Sandbox never reaches the real network.

This route is signed: compute X-Timestamp and X-Signature

Use a Sandbox AppKey. It is used only in this browser to compute the HMAC and is never sent anywhere. The signature covers the body byte for byte, so paste exactly the body you will send. It is valid for 5 minutes.

POST
/api/v1/momo/withdraw

Authorization

PartnerBasic
headerAuthorizationBasic <token>

HTTP Basic auth: your AppId as the username and your AppKey as the password. Sandbox and Live have separate credentials.

Header Parameters

X-Timestamp*string

The current time, ISO 8601 in UTC, e.g. 2026-10-30T11:00:00Z. Must be within 5 minutes of the gateway's clock.

X-Signature*string

Lowercase hex HMAC-SHA256 of "{X-Timestamp}.{raw request body}", keyed with your AppKey. Compute it over the exact bytes you send - see Authentication > Request signing.

Idempotency-Key?string

Optional. A unique key for this request (e.g. a UUID), up to 255 characters. Retrying with the same key and the same body returns the first response again (marked Idempotent-Replayed: true) instead of running the request twice. Kept 24 hours.

Request Body

  1. body

Sends money from your balance to a customer's MTN MoMo wallet.

partnerOrderId*string

Your own unique reference for this payment (max 128 characters). Reusing it never creates a second payment: the gateway returns the existing one with duplicate: true.

msisdn*string

The receiving customer's MTN MoMo number, in international format without +. Check the name on it first with GET /api/v1/kyc/momo/{msisdn}. In Sandbox use a test number.

amount*number

Amount to send, in whole XAF. Your balance must cover it, and it must be within your MOMO_WITHDRAWAL limits.

Formatdouble
currency?|

ISO 4217 currency code. Optional; defaults to XAF, the only currency MTN MoMo Cameroon supports.

Response Body

OK

  1. response
transactionId?string

The gateway's id for the transaction. Use it to trace it (GET /api/v1/partner/transactions/{transactionId}/trace).

Formatuuid
partnerOrderId?string

Your partnerOrderId for this transaction.

status?string

Public status code: GW-00-PENDING, GW-01-SUCCESS, GW-02-FAILED, GW-03-EXPIRED or GW-04-CANCELLED. See Errors and status codes.

failureCode?|

Why it didn't succeed, as a stable code (ACCOUNT_NOT_FOUND, INSUFFICIENT_FUNDS, CUSTOMER_DECLINED, ...). Null unless it failed, expired or was cancelled.

failureMessage?|

A short explanation of failureCode you can show the customer. Null unless it failed.

duplicate?boolean

true when this partnerOrderId already existed: the response describes that existing transaction and nothing new was created.

Example Request
curl -X POST 'https://gateway.staging.wallet2cash.com/api/v1/momo/withdraw' \  -H 'X-Timestamp: string' \  -H 'X-Signature: string' \  -H 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \  -H 'Content-Type: application/json' \  -d '{  "partnerOrderId": "order-2026-10-30-001",  "msisdn": "237670000001",  "amount": 5000}'
Example Response
{  "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc",  "partnerOrderId": "string",  "status": "string",  "failureCode": "string",  "failureMessage": "string",  "duplicate": true}