Requests and errors
The rules every endpoint follows: formats, retries, errors, statuses and limits.
Requests
- Base URL:
https://api.tfolanodal.com. HTTPS only. - Request bodies are JSON with
Content-Type: application/json. Responses are JSON. - Field names are camelCase. Timestamps are ISO 8601 in UTC, like
2026-10-23T08:15:00.000Z. - Ids carry a prefix that says what they are:
cs_checkout session,col_collection,mnd_mandate,rr_repeating request,lnk_payment link,pyt_payout,ref_refund,apr_approval,evt_webhook event.
Amounts and currency
Amounts are in emalangeni (SZL) and sent as decimal strings with up to two decimal places: "250", "250.5" or "250.50". Nodal always returns them with two places, like "250.50". Strings avoid the rounding errors of floating-point numbers; read them into a decimal type, not a float.
currency is always "SZL".
Phone numbers
Send MoMo numbers (msisdn) in international format, digits only, with no + or spaces: 26876123456 — 268followed by the 8-digit Eswatini number. Numbers must belong to the wallet provider you collect through (MTN MoMo today); MTN declines numbers it doesn't recognise.
Idempotency
Networks fail. If a request times out you can't know whether Nodal received it — and retrying a payment request blindly could charge a customer twice. To make retries safe, send an Idempotency-Key header on every request that creates something:
Idempotency-Key: payout-inv-2291- Use a value tied to your own record (an order id, invoice id or a UUID you stored), not a fresh random value per attempt — the point is that a retry sends the same key.
- Repeating a request with the same key and the same body returns the original response; nothing is created twice and the customer is prompted once.
- The same key with a different body is refused with
422: it almost always means a bug that would otherwise charge for the wrong thing. - If the first request is still being processed, a retry gets
409 Duplicate request in flight. Wait a few seconds and retry with the same key. - Keys are remembered for 24 hours and are scoped to your account.
| Endpoint | Idempotency-Key |
|---|---|
POST /checkout/sessions | Required |
POST /collections, /mandates, /payouts, /refunds | Optional, strongly recommended |
POST /payment-links | Not supported — a retry creates a second link |
POST /repeating-requests | Not needed — a retry gets 409 with the existing request's id |
Errors
Errors use standard HTTP status codes and a JSON body with an error message. Some add a message with more detail, or issues listing each invalid field:
{
"error": "Validation failed",
"issues": [
{ "field": "amountSzl", "message": "Amount must be a decimal string" }
]
}| Status | Meaning | What to do |
|---|---|---|
| 200, 201 | Done | |
| 202 | Accepted, still in progress (a payment prompt was sent, or a payout awaits approval) | Wait for the webhook or fetch the object later |
| 400 | Invalid request | Fix the request; don't retry it unchanged |
| 401 | Missing, invalid, revoked or expired API key | Check the key |
| 403 | The key can't be used for this endpoint; or code: "MERCHANT_SUSPENDED": your account is suspended for an unpaid Nodal bill, so new payments can't start | Do it in the portal — see Authentication. If suspended, pay the bill from the Billing page; it works again straight away |
| 404 | Not found in your account | |
| 409 | Conflicts with the object's current state (e.g. cancelling a completed session), or a duplicate in flight | Fetch the object and decide again |
| 422 | Understood but refused: idempotency key reused with a different body, wallet balance too low for a payout, provider not supported | Read error |
| 429 | Too many requests | Back off and retry |
| 500 | Something went wrong at Nodal | Retry with the same Idempotency-Key |
| 502 | MTN definitely rejected the request; the body includes the failed object's id | Read reason; a new attempt needs a new key |
Statuses you must handle
Collections, payouts and refunds move through these statuses (checkout sessions have their own — see Hosted checkout):
| Status | Meaning |
|---|---|
PENDING | Created; not yet sent to MTN (payouts and refunds wait here for approval) |
INITIATED | Sent to MTN; waiting for the customer or for MTN to confirm |
COMPLETED | Money moved. Final. |
FAILED | Declined, timed out or rejected. No money moved. Final. |
CANCELLED | Stopped before any money moved (for example, a rejected payout). Final. |
UNRESOLVED | MTN hasn't confirmed the outcome after repeated checks. Not a failure — money may have moved. Nodal keeps checking and settles it to COMPLETED or FAILED. |
REFUNDED | Collections only: the money was collected and a refund has since completed. |
Never treat INITIATED or UNRESOLVED as failed
The customer may already have approved the payment. Asking them to pay again, or re-sending the request with a new idempotency key, can charge them twice. Wait for a final status.
Lists and pagination
GET /collections, /mandates, /payouts and /refunds return newest first, one page at a time:
| Query parameter | Meaning |
|---|---|
page | Page number, from 1 (default 1) |
limit | Results per page, 1–100 (default 20) |
status | Only this status, e.g. COMPLETED |
search | Matches phone number or reference |
from, to | Created between these dates, e.g. 2026-10-01 and 2026-10-31 (inclusive) |
{
"data": [ { "id": "col_8fK2mQ9xLp", "status": "COMPLETED", "...": "..." } ],
"pagination": {
"page": 1,
"limit": 20,
"total": 57,
"totalPages": 3,
"hasNext": true,
"hasPrev": false
}
}Rate limits
Each client IP address can make 200 requests a minute. Beyond that you get 429 Too many requests with a message saying when to try again. Use webhooks rather than polling in a tight loop.