Repeating requests
A repeating request sends the same customer a MoMo payment prompt every week, month or quarter. They approve each payment with their PIN, the same way they approve a once-off collection, so there is no up-front approval (pre-approval) to set up. Nodal sends the prompts, waits for the customer, and stops if they keep not paying.
Repeating request or mandate?
| Repeating request | Mandate | |
|---|---|---|
| Customer approves | Every payment, with their PIN | Once, up front; later debits need nothing from them |
| If they don't answer | Nothing is paid for that period | The debit goes through if there is money |
| Schedules | Weekly, monthly, quarterly | Daily, weekly, monthly, quarterly, custom |
| Stops by itself | After 3 unpaid periods in a row (you can set 1–6) | Suspended after 3 failed debits in a row |
You can move a customer from a repeating request to a mandate later in the portal. The repeating request ends when they approve the mandate.
How a period works
Each week, month or quarter is a period. A period opens on its due date and stays open for windowDays days (default 3). While it is open, Nodal sends prompts at these times (Eswatini time):
| Window | Prompts |
|---|---|
| 1 day | 08:00, 12:30 and 17:30 on the due date |
| 2–4 days | 08:00 and 17:30 on the first day, 12:00 on the last day |
| 5–7 days | As above, plus 12:00 on a middle day |
- The prompts stop as soon as the period is paid, or when the customer declines one.
- Only one prompt is ever waiting at a time.MTN can't withdraw a prompt, so while one sits unanswered in the customer's MoMo (for example under My Approvals, because their phone was off or locked), Nodal doesn't send another. Otherwise they could approve both and pay twice.
- A period that closes unpaid is
MISSED, orDECLINEDif the customer declined. If a prompt is still waiting when the window closes, it can still be approved; the period then becomesPAID_LATEand the missed count goes back to zero. - After
maxMissedunpaid periods in a row (default 3), the request ends withendedReason: "missed_limit". Problems on MTN's or Nodal's side never count as missed; Nodal retries the prompt instead. - If the number can't pay by MoMo (MTN says it doesn't exist or isn't allowed), the request ends with
endedReason: "payer_invalid". - Two of your requests to the same number on the same day are separate prompts, sent at least 10 minutes apart.
References
Each period's payment carries your reference plus the period, so it reconciles on its own: FEES-G5-2026-11 for a monthly or quarterly request, GYM-0457-2026-11-03 for a weekly one. One number can have several requests (different products or due days), but each live request on a number needs its own reference.
The reference can be changed (below, or in the portal). The new one is used from the next period; open and paid periods keep the reference they went out with. Match payments to your records by id and periodId if you need to follow a request across a change.
Lifecycle
| Status | Meaning |
|---|---|
ACTIVE | Periods open and prompts go out on schedule. |
PAUSED | You paused it. An open period is skipped; nothing is sent until you resume. |
ENDED | No more prompts. endedReason says why: completed (reached endOn or maxPayments), missed_limit, payer_invalid, payer_stopped (the customer stopped it from their link), merchant_ended or moved_to_recurring. |
Each period has its own status:
| Period status | Meaning |
|---|---|
OPEN | Within its window; prompts are going out. |
PAID, PAID_LATE | Paid inside the window, or approved after it closed. |
MISSED, DECLINED | Closed unpaid. Counts towards maxMissed. |
SKIPPED | Not asked for: you skipped or paused it, the request ended, or there was no prompt time left when it was set up. Doesn't count as missed. |
Create a repeating request
/repeating-requestsAPI keyBody parameters
msisdnstringrequired | Customer's MoMo number, 268 plus 8 digits, e.g. 26876123456. |
namestringrequired | 2–60 characters. What it's for. The customer sees it in the prompt with the period, e.g. "Grade 5 fees Nov 2026". |
referencestringrequired | Up to 40 letters, numbers, dots, dashes, slashes or underscores. Unique per number among live requests. |
amountSzlstringrequired | Amount of each payment, e.g. "350.00". |
frequencystringrequired | weekly, monthly or quarterly. |
startOnstringrequired | First due date, YYYY-MM-DD, today or within a year. Sets the weekday (weekly) or day of the month (monthly, quarterly); in shorter months day 29–31 falls on the last day. |
windowDaysintegeroptional | Days each period stays open, 1–7 (weekly: 1–3). Default 3. |
maxMissedintegeroptional | Unpaid periods in a row before it ends, 1–6. Default 3. |
endOnstringoptional | YYYY-MM-DD. No periods open after this day. Leave out for no end. |
maxPaymentsintegeroptional | Ends after this many paid periods, 1–520. Leave out for no limit. |
descriptionstringoptional | Up to 200 characters, for your own records. |
{
"msisdn": "26876123456",
"name": "Grade 5 fees",
"reference": "FEES-G5",
"amountSzl": "350.00",
"frequency": "monthly",
"startOn": "2026-11-03"
}{
"id": "rr_Xb2kP9mQ4wLz",
"name": "Grade 5 fees",
"reference": "FEES-G5",
"msisdn": "26876123456",
"amountSzl": "350.00",
"currency": "SZL",
"frequency": "monthly",
"schedule": "Every month on the 3rd",
"startOn": "2026-11-03",
"endOn": null,
"maxPayments": null,
"windowDays": 3,
"maxMissed": 3,
"status": "ACTIVE",
"nextDueOn": "2026-11-03",
"missedInARow": 0,
"paymentsCount": 0,
"lastPaidAt": null,
"endedReason": null,
"endedAt": null,
"pausedAt": null,
"payLink": "https://app.tfolanodal.com/r/Hq7…",
"createdAt": "2026-11-01T09:12:00.000Z"
}- If
startOnis today, the first period opens straight away and the first prompt goes out within a few minutes (between 07:00 and 19:00 Eswatini time; otherwise the next morning). payLinkis the customer's own page. They can pay the open period from it (the prompt only ever goes to this request's number) or stop the requests. If customer texts are on in the portal, Nodal texts them the link when the request is set up.
Retries are safe without an Idempotency-Key
This endpoint doesn't take an Idempotency-Key. If you retry a create that already worked, you get 409 with the existing request's id, because the number already has a live request with that reference.
{
"error": "This number already has a request with reference FEES-G5 (\"Grade 5 fees\"). Use a different reference for a different product.",
"field": "reference",
"id": "rr_Xb2kP9mQ4wLz"
}Get and list repeating requests
/repeating-requests/:idAPI keyThe request, plus periods (newest first, each with its reference, status, windowEndsAt, promptsSent, lastOutcome, paidCollectionId and its prompts), and upcoming: the next period's due date and prompt times.
/repeating-requestsAPI keyNewest first, paginated with page and limit (up to 100). Filter with status (ACTIVE, PAUSED, ENDED), msisdn, or search (number, reference or name). Each item includes latestPeriod, and the response has counts by status.
Every prompt is also a collection, so GET /collections lists them too, with repeatingRequestId and repeatingCycleId (the period) set.
Change the reference
/repeating-requests/:idAPI keyBody parameters
referencestringrequired | Same rules as when you create it. With an API key, the only field you can change. |
Returns the updated request. Refused with 409if the request has ended, or the number already has another live request with that reference (the response includes that request's id). Sending any other field with an API key gets 403.
Change what happens
Each of these returns the updated request.
/repeating-requests/:id/promptAPI keySend a prompt now for the open period, for example after the customer asks for one. Works after a decline too. Refused with 409 if nothing is due or a prompt is already waiting on their phone, and 429 if the number has had too many prompts in a short time.
/repeating-requests/:id/skipAPI keySkip the open period (its prompts stop), or the next one if none is open. A skipped period doesn't count as missed.
/repeating-requests/:id/pauseAPI keyStops prompts. An open period is skipped.
/repeating-requests/:id/resumeAPI keyResumes a paused request, or restarts an ended one with its missed count back at zero. The next period is the first due date from today; periods that passed while it was stopped aren't asked for. Refused with 409 if its endOn has passed, it moved to a mandate, or the customer stopped it themselves (payer_stopped). In that last case, set up a new request only with the customer's agreement.
/repeating-requests/:id/endAPI keyEnds it (endedReason: "merchant_ended"). A prompt already on the customer's phone can still be approved; that period then shows as PAID_LATE.
Changing the amount, window or limits, and moving a customer to a mandate, are done in the portal.
Webhooks
| Event | When |
|---|---|
repeating_request.created | Set up |
repeating_request.period_opened | A period opened; prompts start |
repeating_request.paid | A period was paid (also late, and duplicates) |
repeating_request.missed | A period closed unpaid |
repeating_request.skipped | A period was skipped |
repeating_request.paused, repeating_request.resumed | Paused, resumed or restarted |
repeating_request.ended | No more prompts; see endedReason |
Each prompt is also a collection, so collection.initiated, collection.completed, collection.failed and collection.unresolved fire too, with repeatingRequestId and periodId. Use repeating_request.paid to mark a period paid: it tells you which period, and whether it was late.
Check for duplicate payments
In rare cases a customer pays the same period twice, when MTN confirms an older prompt late after another one for that period was already paid. The second payment arrives as repeating_request.paid with duplicate: true. Don't count it towards another period; refund it or agree with the customer what it is for.