⬡ Nodal Docs

Payouts

Send money from your MTN MoMo merchant wallet to any MoMo number — suppliers, staff, agents, winners or customers.

How it works

  1. Your server requests a payout. It is saved with status PENDING and an approval request is created.
  2. 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.
  3. On approval Nodal sends the money (INITIATED), and the payout ends COMPLETED or FAILED. On rejection it ends CANCELLED.

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 recommended

Body parameters

msisdnstringrequiredRecipient's MoMo number, e.g. 26876123456.
amountSzlstringrequiredAmount to send, e.g. "500.00".
referencestringrequiredUp to 100 characters, e.g. "Commission Oct 2026".
notestringoptionalUp to 255 characters, for the person approving.
providerstringoptionalDefault mtn_momo.
Request
{
  "msisdn": "26876123456",
  "amountSzl": "500.00",
  "reference": "Commission Oct 2026",
  "note": "Agent 14 — 20 sign-ups"
}
202 Accepted
{
  "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
200 OK
{
  "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 key

Paginated, with status, search, from and to filters — see Lists and pagination.

Webhooks

EventWhen
approval.pendingThe payout is waiting for approval
approval.approved, approval.rejectedSomeone decided
payout.initiatedSent to MTN
payout.completedThe recipient has the money
payout.failedMTN declined it; nothing was sent
payout.cancelledRejected before sending
payout.unresolvedMTN hasn't confirmed the outcome yet — don't pay again