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
- Your server creates a checkout session for the amount and gets back its
url. - You redirect the customer to that URL.
- 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.
- On success the page shows a receipt and sends the customer to your
successUrlafter a few seconds. - 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
| Status | Meaning |
|---|---|
open | Waiting for the customer to pay. They can retry after a declined attempt. |
processing | A payment prompt is on the customer's phone. Only one attempt runs at a time. |
completed | Paid. collectionIdis the payment's id; use it for refunds. |
expired | Not paid before expiresAt. |
cancelled | You 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
/checkout/sessionsAPI key · Idempotency-Key requiredBody parameters
amountSzlstringrequired | Amount to charge, e.g. "149.99". |
referencestringrequired | Up to 64 characters. Shown to the customer on the payment page and receipt, e.g. "Order 1042". |
merchantReferencestringoptional | Up to 128 characters. Your own id for the order; returned on the session and in webhooks, never shown to the customer. |
successUrlstringoptional | HTTPS URL to send the customer to after paying. Nodal adds ?checkout_session_id=cs_…. |
cancelUrlstringoptional | HTTPS URL to send the customer to if the session expires or is cancelled. The session id is added the same way. |
metadataobjectoptional | Your own string key–value pairs, e.g. {"customerId": "c_77"}. Returned on the session and in webhooks. |
expiresInMinutesintegeroptional | How long the customer has to pay: 5 to 1440 minutes. Default 30. |
{
"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
}{
"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
/checkout/sessions/:idAPI keyReturns the session in the same shape as above. Use it to confirm a payment before fulfilling an order.
{
"id": "cs_V1StGXR8Z5jdHi6BmyT2kq0A",
"status": "completed",
"amountSzl": "149.99",
"completedAt": "2026-10-23T10:04:12.000Z",
"collectionId": "col_8fK2mQ9xLp",
"...": "..."
}Cancel a session
/checkout/sessions/:id/cancelAPI keyCancels an opensession, for example when the customer empties their cart. Returns the cancelled session. A session in any other status can't be cancelled:
{
"error": "Cannot cancel a session that is PROCESSING",
"status": "processing"
}Webhooks
| Event | When |
|---|---|
checkout.session.completed | The customer paid. Includes amountSzl, collectionId and your references. |
checkout.session.expired | The session expired unpaid. |
checkout.session.cancelled | You 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
idwith the order, and look it up from your database on the success page rather than trusting thecheckout_session_idin 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.