⬡ Nodal Docs

Event reference

Every webhook event, when it is sent and what its data contains. All events share the envelope described in Receiving webhooks.

Envelope
{
  "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

EventWhenFields
checkout.session.completedThe customer paid. Final, and overrides an earlier expired event.
  • id
  • amountSzl
  • currency
  • reference
  • merchantReference
  • collectionId
  • metadata
  • completedAt
checkout.session.expiredNot paid in time.
  • id
  • reference
  • merchantReference
  • metadata
checkout.session.cancelledYou cancelled it.
  • id
  • reference
  • merchantReference
  • metadata

Collections

Every collections event includes id, reference, msisdn, amountSzl, currency, provider, mandateId (mandate debits only), repeatingRequestId and periodId (repeating request prompts only), plus:

EventWhenExtra fields
collection.initiatedThe payment prompt was sent.
  • status: INITIATED
  • providerReference
  • initiatedAt
collection.completedThe money is in your wallet.
  • status: COMPLETED
  • completedAt
collection.failedDeclined, timed out or rejected. Nothing was taken.
  • status: FAILED
  • failureReason
  • failedAt
collection.unresolvedMTN hasn't confirmed the outcome. Not a failure — wait for completed or failed.
  • status: UNRESOLVED
  • reason
  • unresolvedAt
  • message
collection.refundedA refund of this payment completed.
  • status: REFUNDED
  • refundId
  • refundedAt

Mandates

Every mandates event includes id, reference, msisdn, amountSzl, currency, frequency, plus:

EventWhenExtra fields
mandate.createdCreated; the approval request is on its way.
  • status: PENDING_APPROVAL
  • intervalDays
  • collectionDay
  • firstCollection
  • nextCollectionDate
  • preApprovalReference
  • createdAt
mandate.activatedThe customer approved.
  • status: ACTIVE
  • preApprovalId
  • nextCollectionDate
  • activatedAt
mandate.approval_failedThe approval was declined, went unanswered or was rejected by MTN.
  • status: SUSPENDED
  • preApprovalStatus
  • reason
  • failedAt
mandate.suspendedDebits stopped after repeated failures or a lost approval.
  • status: SUSPENDED
  • consecutiveFailures
  • maxConsecutiveFailures
  • lastFailureReason (if any)
  • preApprovalStatus (if lost)
  • suspendedAt
mandate.pausedYou paused it.
  • status: PAUSED
  • pausedAt
mandate.resumedYou resumed it.
  • status: ACTIVE
  • nextCollectionDate
  • resumedAt
mandate.cancelledYou cancelled it.
  • status: CANCELLED
  • cancelledAt
mandate.completedIt reached its end date.
  • status: COMPLETED
  • collectionsCount
  • completedAt
mandate.reauthorisation_requestedYou re-authorised a suspended mandate; a new approval request was sent.
  • status: PENDING_APPROVAL
  • preApprovalReference
  • nextCollectionDate
  • requestedAt

Mandate debits and renewals

EventWhenFields
mandate.collection_succeededA scheduled debit succeeded.
  • id (the mandate)
  • mandateId
  • collectionId
  • reference
  • msisdn
  • amountSzl
mandate.collection_failedA scheduled debit failed; it will be retried unless the mandate is suspended.
  • id (the mandate)
  • mandateId
  • collectionId
  • reference
  • msisdn
  • amountSzl
  • failureReason
mandate.renewal_requestedThe approval is near expiry; the customer was asked to renew it.
  • id
  • reference
  • msisdn
  • renewalPreApprovalReference
  • currentExpiresAt
  • attempt
mandate.renewedThe customer renewed the approval.
  • id
  • reference
  • msisdn
  • status
  • preApprovalReference
  • preApprovalExpiresAt
  • nextCollectionDate
  • reactivated
mandate.collection_skippedA scheduled debit was skipped because your Nodal account is suspended for an unpaid bill. It isn't collected later.
  • mandateId
  • cycleDate
  • reason: merchant_suspended
  • nextCollectionDate

Repeating requests

Every repeating requests event includes id, name, reference, msisdn, amountSzl, currency, frequency, status, nextDueOn, plus:

EventWhenExtra fields
repeating_request.createdSet up.
  • status: ACTIVE
repeating_request.pausedYou paused it.
  • status: PAUSED
repeating_request.resumedYou resumed it, or restarted an ended one.
  • status: ACTIVE
  • restarted
repeating_request.endedNo more prompts.
  • status: ENDED
  • endedReason: completed | missed_limit | payer_invalid | payer_stopped | merchant_ended | moved_to_recurring
  • endedAt

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:

EventWhenExtra fields
repeating_request.period_openedA period opened; prompts start.
  • status: OPEN
  • windowEndsAt
repeating_request.paidA period was paid. With duplicate: true, it was already paid and this is a second payment.
  • status: PAID | PAID_LATE
  • collectionId
  • late
  • paidAt
  • duplicate (only on a second payment)
repeating_request.missedA period closed unpaid.
  • status: MISSED | DECLINED
  • missedInARow
  • outcome (what happened, in words)
  • promptStillWaiting (a prompt can still be approved)
repeating_request.skippedA period wasn't asked for.
  • status: SKIPPED
  • reason: merchant | not_sent | merchant_suspended
  • windowEndsAt (not with merchant)

Payouts

Every payouts event includes id, reference, msisdn, amountSzl, currency, provider, kind ("standard", or "billing" when Nodal takes its monthly bill), plus:

EventWhenExtra fields
payout.initiatedApproved and sent to MTN.
  • status: INITIATED
  • providerReference
  • initiatedAt
payout.completedThe recipient has the money.
  • status: COMPLETED
  • completedAt
  • financialTransactionId (if MTN gave one)
payout.failedMTN declined it. Nothing was sent.
  • status: FAILED
  • failureReason
  • failedAt
payout.cancelledRejected before anything was sent.
  • status: CANCELLED
  • reason
  • cancelledAt
payout.unresolvedMTN hasn't confirmed the outcome. Don't pay again.
  • status: UNRESOLVED
  • reason
  • unresolvedAt
  • message

Refunds

Every refunds event includes id, originalCollectionId, reference, amountSzl, currency, provider, plus:

EventWhenExtra fields
refund.initiatedApproved and sent to MTN.
  • status: INITIATED
  • providerReference
  • initiatedAt
refund.completedThe customer has the money back.
  • status: COMPLETED
  • completedAt
  • financialTransactionId (if MTN gave one)
refund.failedMTN declined it. Nothing was sent.
  • status: FAILED
  • failureReason
  • failedAt
refund.cancelledRejected before anything was sent.
  • status: CANCELLED
  • reason
  • cancelledAt
refund.unresolvedMTN hasn't confirmed the outcome. Don't refund again.
  • status: UNRESOLVED
  • reason
  • unresolvedAt
  • message

Approvals

EventWhenFields
approval.pendingA payout or refund is waiting for someone to approve it.
  • approvalId
  • entityType: payout | refund
  • payoutId, msisdn, reference (payouts)
  • refundId, originalCollectionId, reason (refunds)
  • requestedBy
  • amountSzl
  • currency
  • provider
approval.approvedApproved; the money is being sent.
  • approvalId
  • entityType
  • entityId
  • approvedBy
  • note (if given)
approval.rejectedRejected; nothing will be sent.
  • approvalId
  • entityType
  • entityId
  • rejectedBy
  • reason