MobileWalletPartner Gateway Docs

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 }
  ]
}
  • reference is 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 msisdn and amount (whole XAF). partnerOrderId is optional; without it the payout's order id is {reference}-{row}.
  • name is 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_WITHDRAWAL minimum 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 statusMeaning
QUEUEDNot sent yet.
REJECTEDNot sent, no money moved: see rejectionCode.
PENDINGSent, waiting for the operator.
SUCCEEDEDPaid.
FAILEDSent 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:

rejectionCodeWhy
NAME_MISMATCHThe registered name is different. registeredName shows it.
ACCOUNT_INACTIVEThe number has no active MoMo account.
NAME_CHECK_FAILEDThe name couldn't be checked (the operator didn't answer).
REFUSEDA 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".