⬡ Nodal Docs

Mandates (debit orders)

A mandate lets you collect the same amount from a customer on a schedule — weekly gym fees, monthly rent, quarterly insurance. The customer approves it once on their phone; Nodal then debits their MoMo wallet on each due date, retries failed debits and keeps you informed.

Lifecycle

StatusMeaning
PENDING_APPROVALCreated. MTN has sent the customer an approval request; nothing is debited until they approve it.
ACTIVEApproved. Debits run on each due date.
PAUSEDYou paused it. No debits until you resume it.
SUSPENDEDNodal stopped debiting: too many failed debits in a row, the customer declined or let the approval lapse, or the approval expired. See Suspended mandates.
CANCELLEDYou cancelled it. Final.
COMPLETEDReached its endDate. Final.

Schedule

  • frequency is daily, weekly, monthly, quarterly, or custom with intervalDays (1–365).
  • Monthly and quarterly mandates can debit on a fixed collectionDay(1–31). In shorter months, day 29–31 falls on the month's last day.
  • Debits run from 09:00 Eswatini time on each due date. By default the first debit is on the first due date after startDate; set firstCollection to immediate to debit as soon as the customer approves (only when startDate is today).
  • A failed debit is retried after retryIntervalDays (default 3). After 3 failed debits in a row the mandate is SUSPENDED.

Create a mandate

POST/mandatesAPI key · Idempotency-Key recommended

Body parameters

msisdnstringrequiredCustomer's MoMo number, e.g. 26876123456.
amountSzlstringrequiredAmount of each debit, e.g. "350.00". Must be a string.
frequencystringrequireddaily, weekly, monthly, quarterly or custom.
startDatestringrequiredISO 8601 date-time, today or later, e.g. 2026-11-01T00:00:00+02:00.
referencestringrequiredUp to 100 characters. Your reference for the agreement, e.g. a membership number.
descriptionstringoptionalUp to 255 characters. Shown to the customer in the approval request (the reference is used if you leave it out).
intervalDaysintegeroptionalDays between debits. Required when frequency is custom.
collectionDayintegeroptionalDay of the month to debit, 1–31. Monthly and quarterly only.
firstCollectionstringoptionalon_schedule (default) or immediate.
retryIntervalDaysintegeroptionalDays to wait before retrying a failed debit, 0–30. Default 3.
endDatestringoptionalISO 8601 date-time after which the mandate completes. Leave out for no end.
providerstringoptionalDefault mtn_momo.
Request
{
  "msisdn": "26876123456",
  "amountSzl": "350.00",
  "frequency": "monthly",
  "collectionDay": 1,
  "startDate": "2026-11-01T00:00:00+02:00",
  "reference": "MEMBER-0457",
  "description": "Ezulwini Gym monthly membership"
}
201 Created
{
  "id": "mnd_q3Lx8Pz2Kd",
  "status": "PENDING_APPROVAL",
  "frequency": "monthly",
  "intervalDays": 30,
  "collectionDay": 1,
  "nextCollectionDate": "2026-11-01T07:00:00.000Z",
  "reference": "MEMBER-0457",
  "preApprovalReference": "0d6c…",
  "preApprovalRequested": true,
  "correlationId": "…"
}

preApprovalRequested: falsemeans MTN didn't confirm it received the approval request. The mandate stays PENDING_APPROVAL while Nodal checks; it becomes ACTIVE if the customer approves, or SUSPENDED if the request failed.

Tell the customer to expect the prompt

The approval request comes from MTN, not from you. Tell the customer to approve it on their phone, or they may ignore it. If you have turned on customer text messages in the portal, Nodal also texts them about the mandate.

Get and list mandates

GET/mandates/:idAPI key

The mandate, including status, nextCollectionDate, consecutiveFailures, preApprovalStatus and preApprovalExpiresAt(when the customer's approval runs out).

GET/mandatesAPI key

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

GET/mandates/:id/collectionsAPI key

Every debit under the mandate, newest first. Paginated, with an optional status filter.

Change the reference

PATCH/mandates/:idAPI key

Body parameters

referencestringrequiredUp to 100 characters. The only field you can change.
200 OK
{ "id": "mnd_q3Lx8Pz2Kd", "reference": "MEMBER-0457-B" }

Debits from then on carry the new reference; past debits keep theirs. The customer's approval at MTN is unchanged and they aren't asked again. Your team can also change it in the portal, so match debits to your records by mandateId if you need to follow a mandate across a change. Refused with 409 for a cancelled or completed mandate.

Pause, resume and cancel

POST/mandates/:id/pauseAPI key

Stops debits until you resume. Returns { "id": "mnd_…", "status": "PAUSED" }.

POST/mandates/:id/resumeAPI key

Restarts a paused or suspended mandate. If due dates passed while it was stopped, the schedule restarts from today rather than debiting for the missed dates. Returns the new nextCollectionDate. Refused with 409if the customer's approval has expired or been revoked (re-authorise instead), or the mandate has passed its end date.

POST/mandates/:id/cancelAPI key

Ends the mandate for good and withdraws the approval with MTN. Returns { "id": "mnd_…", "status": "CANCELLED" }. If MTN can't be reached to withdraw the approval, you get 502 and the mandate is left unchanged — retry the request.

Suspended mandates

Check the mandate's preApprovalStatus to see why it stopped:

  • Approval still valid (debits failed, e.g. the wallet was empty three times): sort it out with the customer, then resume.
  • Approval lost (preApprovalStatus is EXPIRED, CANCELLED or FAILED): re-authorise. The customer gets a new approval request; the mandate becomes ACTIVE again when they approve it.
POST/mandates/:id/reauthoriseAPI key
200 OK
{
  "id": "mnd_q3Lx8Pz2Kd",
  "status": "PENDING_APPROVAL",
  "preApprovalReference": "7be2…",
  "preApprovalRequested": true,
  "nextCollectionDate": "2026-12-01T07:00:00.000Z"
}

Approval renewal

MTN approvals have an expiry. Fourteen days before a mandate's approval runs out, Nodal automatically asks the customer to renew it, and debits carry on meanwhile. You receive mandate.renewal_requested and then mandate.renewed when the customer approves. An unanswered request is repeated after 5 days, up to 3 times. If the customer never approves, the mandate is suspended when the old approval expires; a renewal approved after that brings it back to ACTIVE from its next due date.

Webhooks

EventWhen
mandate.createdCreated; approval requested
mandate.activatedThe customer approved
mandate.approval_failedThe approval was declined, expired unanswered or rejected by MTN
mandate.collection_succeededA debit succeeded
mandate.collection_failedA debit failed (it will be retried)
mandate.suspendedDebits stopped
mandate.paused, mandate.resumed, mandate.cancelledYou changed it
mandate.reauthorisation_requestedYou re-authorised a suspended mandate
mandate.renewal_requested, mandate.renewedAutomatic approval renewal
mandate.completedReached its end date

Each debit is also a collection, so collection.completed and collection.failed fire too, with the mandateId.