Event reference
Every webhook event, when it is sent and what its data contains. All events share the envelope described in Receiving webhooks.
{
"id": "evt_Lw8kQ2xP9mRt3v",
"type": "collection.completed",
"createdAt": "2026-10-23T08:15:41.000Z",
"data": {
"id": "col_8fK2mQ9xLp",
"reference": "Invoice 2291",
"msisdn": "26876123456",
"amountSzl": "250.00",
"currency": "SZL",
"provider": "mtn_momo",
"status": "COMPLETED",
"completedAt": "2026-10-23T08:15:41.000Z"
}
}New fields can appear
Nodal may add fields to datawithout notice. Ignore fields you don't know rather than rejecting the event.
You choose which events each endpoint receives in the portal. webhook.test is sent only by the Send testbutton and can't be subscribed to.
Checkout sessions
| Event | When | Fields |
|---|---|---|
checkout.session.completed | The customer paid. Final, and overrides an earlier expired event. |
|
checkout.session.expired | Not paid in time. |
|
checkout.session.cancelled | You cancelled it. |
|
Collections
Every collections event includes id, reference, msisdn, amountSzl, currency, provider, mandateId (mandate debits only), repeatingRequestId and periodId (repeating request prompts only), plus:
| Event | When | Extra fields |
|---|---|---|
collection.initiated | The payment prompt was sent. |
|
collection.completed | The money is in your wallet. |
|
collection.failed | Declined, timed out or rejected. Nothing was taken. |
|
collection.unresolved | MTN hasn't confirmed the outcome. Not a failure — wait for completed or failed. |
|
collection.refunded | A refund of this payment completed. |
|
Mandates
Every mandates event includes id, reference, msisdn, amountSzl, currency, frequency, plus:
| Event | When | Extra fields |
|---|---|---|
mandate.created | Created; the approval request is on its way. |
|
mandate.activated | The customer approved. |
|
mandate.approval_failed | The approval was declined, went unanswered or was rejected by MTN. |
|
mandate.suspended | Debits stopped after repeated failures or a lost approval. |
|
mandate.paused | You paused it. |
|
mandate.resumed | You resumed it. |
|
mandate.cancelled | You cancelled it. |
|
mandate.completed | It reached its end date. |
|
mandate.reauthorisation_requested | You re-authorised a suspended mandate; a new approval request was sent. |
|
Mandate debits and renewals
| Event | When | Fields |
|---|---|---|
mandate.collection_succeeded | A scheduled debit succeeded. |
|
mandate.collection_failed | A scheduled debit failed; it will be retried unless the mandate is suspended. |
|
mandate.renewal_requested | The approval is near expiry; the customer was asked to renew it. |
|
mandate.renewed | The customer renewed the approval. |
|
mandate.collection_skipped | A scheduled debit was skipped because your Nodal account is suspended for an unpaid bill. It isn't collected later. |
|
Repeating requests
Every repeating requests event includes id, name, reference, msisdn, amountSzl, currency, frequency, status, nextDueOn, plus:
| Event | When | Extra fields |
|---|---|---|
repeating_request.created | Set up. |
|
repeating_request.paused | You paused it. |
|
repeating_request.resumed | You resumed it, or restarted an ended one. |
|
repeating_request.ended | No more prompts. |
|
Repeating request periods
Every repeating request periods event includes id (the repeating request), repeatingRequestId, periodId, dueOn, period (e.g. "Nov 2026"), reference (with the period), name, msisdn, amountSzl, currency, status (the period's), plus:
| Event | When | Extra fields |
|---|---|---|
repeating_request.period_opened | A period opened; prompts start. |
|
repeating_request.paid | A period was paid. With duplicate: true, it was already paid and this is a second payment. |
|
repeating_request.missed | A period closed unpaid. |
|
repeating_request.skipped | A period wasn't asked for. |
|
Payouts
Every payouts event includes id, reference, msisdn, amountSzl, currency, provider, kind ("standard", or "billing" when Nodal takes its monthly bill), plus:
| Event | When | Extra fields |
|---|---|---|
payout.initiated | Approved and sent to MTN. |
|
payout.completed | The recipient has the money. |
|
payout.failed | MTN declined it. Nothing was sent. |
|
payout.cancelled | Rejected before anything was sent. |
|
payout.unresolved | MTN hasn't confirmed the outcome. Don't pay again. |
|
Refunds
Every refunds event includes id, originalCollectionId, reference, amountSzl, currency, provider, plus:
| Event | When | Extra fields |
|---|---|---|
refund.initiated | Approved and sent to MTN. |
|
refund.completed | The customer has the money back. |
|
refund.failed | MTN declined it. Nothing was sent. |
|
refund.cancelled | Rejected before anything was sent. |
|
refund.unresolved | MTN hasn't confirmed the outcome. Don't refund again. |
|
Approvals
| Event | When | Fields |
|---|---|---|
approval.pending | A payout or refund is waiting for someone to approve it. |
|
approval.approved | Approved; the money is being sent. |
|
approval.rejected | Rejected; nothing will be sent. |
|