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
| Status | Meaning |
|---|---|
PENDING_APPROVAL | Created. MTN has sent the customer an approval request; nothing is debited until they approve it. |
ACTIVE | Approved. Debits run on each due date. |
PAUSED | You paused it. No debits until you resume it. |
SUSPENDED | Nodal stopped debiting: too many failed debits in a row, the customer declined or let the approval lapse, or the approval expired. See Suspended mandates. |
CANCELLED | You cancelled it. Final. |
COMPLETED | Reached its endDate. Final. |
Schedule
frequencyisdaily,weekly,monthly,quarterly, orcustomwithintervalDays(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; setfirstCollectiontoimmediateto debit as soon as the customer approves (only whenstartDateis today). - A failed debit is retried after
retryIntervalDays(default 3). After 3 failed debits in a row the mandate isSUSPENDED.
Create a mandate
/mandatesAPI key · Idempotency-Key recommendedBody parameters
msisdnstringrequired | Customer's MoMo number, e.g. 26876123456. |
amountSzlstringrequired | Amount of each debit, e.g. "350.00". Must be a string. |
frequencystringrequired | daily, weekly, monthly, quarterly or custom. |
startDatestringrequired | ISO 8601 date-time, today or later, e.g. 2026-11-01T00:00:00+02:00. |
referencestringrequired | Up to 100 characters. Your reference for the agreement, e.g. a membership number. |
descriptionstringoptional | Up to 255 characters. Shown to the customer in the approval request (the reference is used if you leave it out). |
intervalDaysintegeroptional | Days between debits. Required when frequency is custom. |
collectionDayintegeroptional | Day of the month to debit, 1–31. Monthly and quarterly only. |
firstCollectionstringoptional | on_schedule (default) or immediate. |
retryIntervalDaysintegeroptional | Days to wait before retrying a failed debit, 0–30. Default 3. |
endDatestringoptional | ISO 8601 date-time after which the mandate completes. Leave out for no end. |
providerstringoptional | Default mtn_momo. |
{
"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"
}{
"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
/mandates/:idAPI keyThe mandate, including status, nextCollectionDate, consecutiveFailures, preApprovalStatus and preApprovalExpiresAt(when the customer's approval runs out).
/mandatesAPI keyPaginated, with status, search, from and to filters — see Lists and pagination.
/mandates/:id/collectionsAPI keyEvery debit under the mandate, newest first. Paginated, with an optional status filter.
Change the reference
/mandates/:idAPI keyBody parameters
referencestringrequired | Up to 100 characters. The only field you can change. |
{ "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
/mandates/:id/pauseAPI keyStops debits until you resume. Returns { "id": "mnd_…", "status": "PAUSED" }.
/mandates/:id/resumeAPI keyRestarts 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.
/mandates/:id/cancelAPI keyEnds 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 (
preApprovalStatusisEXPIRED,CANCELLEDorFAILED): re-authorise. The customer gets a new approval request; the mandate becomesACTIVEagain when they approve it.
/mandates/:id/reauthoriseAPI key{
"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
| Event | When |
|---|---|
mandate.created | Created; approval requested |
mandate.activated | The customer approved |
mandate.approval_failed | The approval was declined, expired unanswered or rejected by MTN |
mandate.collection_succeeded | A debit succeeded |
mandate.collection_failed | A debit failed (it will be retried) |
mandate.suspended | Debits stopped |
mandate.paused, mandate.resumed, mandate.cancelled | You changed it |
mandate.reauthorisation_requested | You re-authorised a suspended mandate |
mandate.renewal_requested, mandate.renewed | Automatic approval renewal |
mandate.completed | Reached its end date |
Each debit is also a collection, so collection.completed and collection.failed fire too, with the mandateId.