⬡ Nodal Docs

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:

HTTP
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.
EndpointIdempotency-Key
POST /checkout/sessionsRequired
POST /collections, /mandates, /payouts, /refundsOptional, strongly recommended
POST /payment-linksNot supported — a retry creates a second link
POST /repeating-requestsNot 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:

400 Bad Request
{
  "error": "Validation failed",
  "issues": [
    { "field": "amountSzl", "message": "Amount must be a decimal string" }
  ]
}
StatusMeaningWhat to do
200, 201Done
202Accepted, still in progress (a payment prompt was sent, or a payout awaits approval)Wait for the webhook or fetch the object later
400Invalid requestFix the request; don't retry it unchanged
401Missing, invalid, revoked or expired API keyCheck the key
403The 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 startDo it in the portal — see Authentication. If suspended, pay the bill from the Billing page; it works again straight away
404Not found in your account
409Conflicts with the object's current state (e.g. cancelling a completed session), or a duplicate in flightFetch the object and decide again
422Understood but refused: idempotency key reused with a different body, wallet balance too low for a payout, provider not supportedRead error
429Too many requestsBack off and retry
500Something went wrong at NodalRetry with the same Idempotency-Key
502MTN definitely rejected the request; the body includes the failed object's idRead 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):

StatusMeaning
PENDINGCreated; not yet sent to MTN (payouts and refunds wait here for approval)
INITIATEDSent to MTN; waiting for the customer or for MTN to confirm
COMPLETEDMoney moved. Final.
FAILEDDeclined, timed out or rejected. No money moved. Final.
CANCELLEDStopped before any money moved (for example, a rejected payout). Final.
UNRESOLVEDMTN 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.
REFUNDEDCollections 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 parameterMeaning
pagePage number, from 1 (default 1)
limitResults per page, 1–100 (default 20)
statusOnly this status, e.g. COMPLETED
searchMatches phone number or reference
from, toCreated between these dates, e.g. 2026-10-01 and 2026-10-31 (inclusive)
200 OK
{
  "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.