Payouts
Send money from your MTN MoMo merchant wallet to any MoMo number — suppliers, staff, agents, winners or customers.
How it works
- Your server requests a payout. It is saved with status
PENDINGand an approval request is created. - A person on your team approves or rejects it under Approvalsin the portal. The person who requested a payout can't approve it, and an API key never can.
- On approval Nodal sends the money (
INITIATED), and the payout endsCOMPLETEDorFAILED. On rejection it endsCANCELLED.
Before you start
Payouts need your MTN disbursement keys saved in the portal under Settings, as well as your collection keys. MTN charges a fee on each payout (1% of the amount), taken from your wallet.
Request a payout
POST
/payoutsAPI key · Idempotency-Key recommendedBody parameters
msisdnstringrequired | Recipient's MoMo number, e.g. 26876123456. |
amountSzlstringrequired | Amount to send, e.g. "500.00". |
referencestringrequired | Up to 100 characters, e.g. "Commission Oct 2026". |
notestringoptional | Up to 255 characters, for the person approving. |
providerstringoptional | Default mtn_momo. |
{
"msisdn": "26876123456",
"amountSzl": "500.00",
"reference": "Commission Oct 2026",
"note": "Agent 14 — 20 sign-ups"
}{
"id": "pyt_Rk2Lw9Qx4M",
"status": "PENDING_APPROVAL",
"approvalRequestId": "apr_7Hn3Kd8Pq2",
"amountSzl": "500.00",
"currency": "SZL",
"correlationId": "…",
"message": "Payout requires approval before funds are released"
}The response says PENDING_APPROVAL; when you fetch the payout its status is PENDING until someone decides.
If your wallet can't cover the amount plus MTN's fee — after everything already waiting for approval or in progress — the request is refused with 422 and nothing is created. The balance is checked again at approval.
Get and list payouts
GET
/payouts/:idAPI key{
"id": "pyt_Rk2Lw9Qx4M",
"msisdn": "26876123456",
"amountSzl": "500.00",
"currency": "SZL",
"reference": "Commission Oct 2026",
"status": "COMPLETED",
"provider": "mtn_momo",
"createdAt": "2026-10-23T08:15:00.000Z",
"completedAt": "2026-10-23T09:02:10.000Z",
"failureReason": null,
"...": "..."
}GET
/payoutsAPI keyPaginated, with status, search, from and to filters — see Lists and pagination.
Webhooks
| Event | When |
|---|---|
approval.pending | The payout is waiting for approval |
approval.approved, approval.rejected | Someone decided |
payout.initiated | Sent to MTN |
payout.completed | The recipient has the money |
payout.failed | MTN declined it; nothing was sent |
payout.cancelled | Rejected before sending |
payout.unresolved | MTN hasn't confirmed the outcome yet — don't pay again |