⬡ Nodal Docs

Refunds

Give some or all of a completed payment back to the MoMo number that paid it. Like payouts, every refund waits for a person on your team to approve it.

Rules

  • Only a COMPLETED collection can be refunded — from any source: checkout (use the session's collectionId), payment link, direct collection or mandate debit.
  • The money goes back to the number that paid; you can't choose another.
  • You can refund the full amount or less, but never more than was paid.
  • One refund per payment. While a refund is waiting, in progress or completed, another is refused. A rejected or failed refund doesn't count, so you can try again.
  • Refunds use your MTN disbursement keys and carry MTN's 1% fee, taken from your wallet. The wallet must cover the refund plus the fee.
  • When the refund completes, the original collection's status becomes REFUNDED. A refunded payment still counts towards your Nodal bill.

Request a refund

POST/refundsAPI key · Idempotency-Key recommended

Body parameters

collectionIdstringrequiredThe payment to refund, e.g. col_8fK2mQ9xLp.
amountSzlstringoptionalAmount to refund. Leave out to refund everything.
reasonstringoptionalUp to 255 characters, for the person approving and your records.
Request
{
  "collectionId": "col_8fK2mQ9xLp",
  "amountSzl": "50.00",
  "reason": "One item out of stock"
}
202 Accepted
{
  "id": "ref_T4mK9pW2xQ",
  "status": "PENDING_APPROVAL",
  "approvalRequestId": "apr_2Lq8Nd4Hx7",
  "amountSzl": "50.00",
  "...": "...",
  "message": "Refund requires approval before funds are returned"
}
ErrorWhy
404 Collection not foundWrong id, or not your payment
409 Cannot refund a collection with status …The payment isn't COMPLETED
409 Collection already has a pending or completed refundOne refund per payment
400 Refund amount cannot exceed the original collection amount
422Your wallet can't cover the refund plus MTN's fee

Get and list refunds

GET/refunds/:idAPI key

Includes originalCollectionId, amountSzl, reason, status, completedAt and failureReason.

GET/refundsAPI key

Paginated, with status, search, from and to filters, plus collectionId to see the refunds of one payment.

Webhooks

approval.pending, approval.approved, approval.rejected, then refund.initiated, refund.completed (with collection.refunded for the original payment), refund.failed, refund.cancelled or refund.unresolved. See the event reference.