Bulk payouts
Pay up to 500 MoMo numbers in one request or one CSV upload, with an optional name check per payout.
A bulk payout sends many MoMo withdrawals from your balance at once: salaries, commissions,
refunds of a cancelled event. Each payout is an ordinary withdrawal:
it counts against your MOMO_WITHDRAWAL limits, is debited from your balance, appears in your
transactions and sends its own webhook.
Create one
POST /api/v1/payouts, signed like a
withdrawal:
{
"reference": "salaries-2026-10",
"items": [
{ "msisdn": "237670000001", "amount": 150000, "name": "Jane Sandbox", "partnerOrderId": "salary-001" },
{ "msisdn": "237670000002", "amount": 90000 }
]
}referenceis your id for the batch, unique for your account. Sending the same reference again returns the existing batch (duplicate: true) instead of paying twice. Optional.- Each item needs
msisdnandamount(whole XAF).partnerOrderIdis optional; without it the payout's order id is{reference}-{row}. nameis optional: see the name check.
Checked as a whole first
The whole batch is accepted or refused before anything is sent. A refusal is a 400 whose
errors list every problem by row:
- 1 to 500 payouts, numbers in international format, amounts above 0 in whole XAF;
- each amount within your
MOMO_WITHDRAWALminimum and maximum; - order ids unique within the batch and not used by any earlier transaction;
- the total covered by your balance (Sandbox and Live have separate balances).
Follow it
The response is the batch with status: "PROCESSING". Payouts are then sent one by one, in row
order. GET /api/v1/payouts/{id} returns the batch with every payout's outcome, and
GET /api/v1/payouts lists your batches.
| Payout status | Meaning |
|---|---|
QUEUED | Not sent yet. |
REJECTED | Not sent, no money moved: see rejectionCode. |
PENDING | Sent, waiting for the operator. |
SUCCEEDED | Paid. |
FAILED | Sent but failed, expired or cancelled at the operator: see failureCode. |
The batch becomes COMPLETED once every payout has been sent or rejected. Each sent payout then
settles like any withdrawal: you get its webhook, and it appears in the Events API.
The name check
When a payout has a name, the gateway first looks up the name MTN has registered for the number.
The payout is only sent if they match; otherwise it is REJECTED and nothing is paid:
rejectionCode | Why |
|---|---|
NAME_MISMATCH | The registered name is different. registeredName shows it. |
ACCOUNT_INACTIVE | The number has no active MoMo account. |
NAME_CHECK_FAILED | The name couldn't be checked (the operator didn't answer). |
REFUSED | A limit or your balance refused it when it was sent (e.g. the daily limit). |
Names are compared ignoring case, accents, punctuation and word order. They match when they have the same words, or share at least two: "Fopa Duclair" matches "FOPA KUETE Duclair", but a surname alone does not match.
From the dashboard
On the partner dashboard's Payouts page, a PartnerAdmin can upload a CSV:
msisdn,amount,name,reference
237670000001,150000,Jane Sandbox,salary-001
237670000002,90000,,Only msisdn and amount are required; French headers (numero, montant, nom) and
semicolon-separated files from Excel work too. Before anything is sent the page shows every row
with MTN's registered name and whether it matches, the total and your balance. Sending asks for
your password and an authenticator code.
In Sandbox
Use the test numbers: 237670000001 is paid, 237670000002 fails with
ACCOUNT_NOT_FOUNDNo mobile money account was found for this number., and their registered name is "Jane Sandbox".
