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
COMPLETEDcollection can be refunded — from any source: checkout (use the session'scollectionId), 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 recommendedBody parameters
collectionIdstringrequired | The payment to refund, e.g. col_8fK2mQ9xLp. |
amountSzlstringoptional | Amount to refund. Leave out to refund everything. |
reasonstringoptional | Up to 255 characters, for the person approving and your records. |
{
"collectionId": "col_8fK2mQ9xLp",
"amountSzl": "50.00",
"reason": "One item out of stock"
}{
"id": "ref_T4mK9pW2xQ",
"status": "PENDING_APPROVAL",
"approvalRequestId": "apr_2Lq8Nd4Hx7",
"amountSzl": "50.00",
"...": "...",
"message": "Refund requires approval before funds are returned"
}| Error | Why |
|---|---|
404 Collection not found | Wrong 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 refund | One refund per payment |
400 Refund amount cannot exceed the original collection amount | |
422 | Your wallet can't cover the refund plus MTN's fee |
Get and list refunds
GET
/refunds/:idAPI keyIncludes originalCollectionId, amountSzl, reason, status, completedAt and failureReason.
GET
/refundsAPI keyPaginated, 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.