⬡ Nodal Docs

Hosted checkout

Send your customer to a Nodal payment page for an order and get them back when they've paid. You don't build a payment form, handle phone numbers or wait for MoMo prompts — the page does all of that.

How it works

  1. Your server creates a checkout session for the amount and gets back its url.
  2. You redirect the customer to that URL.
  3. The page shows your business name, the amount and the payment options you have set up. The customer enters their MoMo number and approves the prompt on their phone.
  4. On success the page shows a receipt and sends the customer to your successUrl after a few seconds.
  5. Your server confirms the payment — by fetching the session or receiving checkout.session.completed — and fulfils the order.

Always confirm on your server

The redirect to your successUrlis for the customer's convenience only. Anyone can type that URL. Fulfil an order only when GET /checkout/sessions/:id says completed or you receive a verified checkout.session.completed webhook.

Session statuses

StatusMeaning
openWaiting for the customer to pay. They can retry after a declined attempt.
processingA payment prompt is on the customer's phone. Only one attempt runs at a time.
completedPaid. collectionIdis the payment's id; use it for refunds.
expiredNot paid before expiresAt.
cancelledYou cancelled it.

A late payment still counts

If a customer approves the prompt just as the session expires, MTN's confirmation can arrive afterwards. The session then becomes completed even though you may already have seen checkout.session.expired. Treat completed as final and let it override an earlier expiry: the customer has paid.

Create a session

POST/checkout/sessionsAPI key · Idempotency-Key required

Body parameters

amountSzlstringrequiredAmount to charge, e.g. "149.99".
referencestringrequiredUp to 64 characters. Shown to the customer on the payment page and receipt, e.g. "Order 1042".
merchantReferencestringoptionalUp to 128 characters. Your own id for the order; returned on the session and in webhooks, never shown to the customer.
successUrlstringoptionalHTTPS URL to send the customer to after paying. Nodal adds ?checkout_session_id=cs_….
cancelUrlstringoptionalHTTPS URL to send the customer to if the session expires or is cancelled. The session id is added the same way.
metadataobjectoptionalYour own string key–value pairs, e.g. {"customerId": "c_77"}. Returned on the session and in webhooks.
expiresInMinutesintegeroptionalHow long the customer has to pay: 5 to 1440 minutes. Default 30.
Request
{
  "amountSzl": "149.99",
  "reference": "Order 1042",
  "merchantReference": "order_1042",
  "successUrl": "https://shop.example.com/orders/1042/paid",
  "cancelUrl": "https://shop.example.com/cart",
  "metadata": { "customerId": "c_77" },
  "expiresInMinutes": 30
}
201 Created
{
  "id": "cs_V1StGXR8Z5jdHi6BmyT2kq0A",
  "url": "https://app.tfolanodal.com/checkout/cs_V1StGXR8Z5jdHi6BmyT2kq0A",
  "status": "open",
  "amountSzl": "149.99",
  "currency": "SZL",
  "reference": "Order 1042",
  "merchantReference": "order_1042",
  "metadata": { "customerId": "c_77" },
  "expiresAt": "2026-10-23T10:30:00.000Z",
  "completedAt": null,
  "collectionId": null
}

Repeating the request with the same Idempotency-Key and body returns the same session with 200. The same key with a different amount, reference, URLs or metadata is refused with 422.

Get a session

GET/checkout/sessions/:idAPI key

Returns the session in the same shape as above. Use it to confirm a payment before fulfilling an order.

200 OK — paid
{
  "id": "cs_V1StGXR8Z5jdHi6BmyT2kq0A",
  "status": "completed",
  "amountSzl": "149.99",
  "completedAt": "2026-10-23T10:04:12.000Z",
  "collectionId": "col_8fK2mQ9xLp",
  "...": "..."
}

Cancel a session

POST/checkout/sessions/:id/cancelAPI key

Cancels an opensession, for example when the customer empties their cart. Returns the cancelled session. A session in any other status can't be cancelled:

409 Conflict
{
  "error": "Cannot cancel a session that is PROCESSING",
  "status": "processing"
}

Webhooks

EventWhen
checkout.session.completedThe customer paid. Includes amountSzl, collectionId and your references.
checkout.session.expiredThe session expired unpaid.
checkout.session.cancelledYou cancelled the session.

Payloads are in the event reference.

Good practice

  • Create one session per order, and reuse it if the customer clicks "Pay" again while it is open.
  • Use your order id in the Idempotency-Key (e.g. checkout-order_1042).
  • Store the session id with the order, and look it up from your database on the success page rather than trusting the checkout_session_id in the URL.
  • The payment page needs collection keys saved in your portal. If none are set up, the page tells the customer payment isn't available.