Quickstart
Take your first payment with hosted checkout: your server creates a checkout session, your customer pays on Nodal's payment page, and your server confirms the payment before fulfilling the order.
This is a real payment
There is no test mode yet, so this guide charges a real MTN MoMo wallet. Use your own number and E1.00, then refund yourself from the portal. See Testing and going live.
Before you start
- A Nodal account at app.tfolanodal.com with your MTN MoMo collection keys saved under Settings.
- A server that can make HTTPS requests. The examples use PHP, Node.js 18+ and Python 3 with
requests.
Create an API key
In the portal, open Integrations and create an API key. Only owners and admins can do this. The key starts with
np_live_and is shown once: store it in your server's environment (for exampleNODAL_API_KEY), never in your code, a web page or a mobile app.Create a checkout session
When the customer clicks "Pay", your server creates a session for the order. Send an
Idempotency-Keythat is unique to the order, so a retried request can never create a second session.<?php $orderId = "order_1042"; $ch = curl_init("https://api.tfolanodal.com/checkout/sessions"); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("NODAL_API_KEY"), "Content-Type: application/json", "Idempotency-Key: checkout-" . $orderId, ], CURLOPT_POSTFIELDS => json_encode([ "amountSzl" => "1.00", "reference" => "Order 1042", "merchantReference" => $orderId, "successUrl" => "https://shop.example.com/orders/1042/paid", "cancelUrl" => "https://shop.example.com/cart", ]), ]); $session = json_decode(curl_exec($ch), true); // Send the customer to Nodal's payment page. header("Location: " . $session["url"]);The response includes the session's
idand theurlof its payment page:{ "id": "cs_V1StGXR8Z5jdHi6BmyT2kq0A", "url": "https://app.tfolanodal.com/checkout/cs_V1StGXR8Z5jdHi6BmyT2kq0A", "status": "open", "amountSzl": "1.00", "currency": "SZL", "reference": "Order 1042", "merchantReference": "order_1042", "metadata": null, "expiresAt": "2026-10-23T10:30:00.000Z", "completedAt": null, "collectionId": null }Save the session
idagainst the order: you need it to confirm the payment.The customer pays
On the payment page the customer sees your business name and the amount, enters their MoMo number and approves the prompt on their phone with their PIN. When the payment succeeds, Nodal sends them back to your
successUrlwith the session id added:https://shop.example.com/orders/1042/paid?checkout_session_id=cs_V1StGXR8Z5jdHi6BmyT2kq0AConfirm the payment on your server
Arriving at your success page proves nothing — anyone can open that URL. Before you fulfil the order, fetch the session from your server and check that its
statusiscompleted:<?php $sessionId = $savedOrder["checkout_session_id"]; // from your database, not the URL $ch = curl_init("https://api.tfolanodal.com/checkout/sessions/" . urlencode($sessionId)); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("NODAL_API_KEY")], ]); $session = json_decode(curl_exec($ch), true); if ($session["status"] === "completed") { markOrderPaid($orderId, $session["collectionId"]); }Also listen for the webhook
Customers sometimes close the page before they are sent back. Subscribe to
checkout.session.completedso your server hears about every payment, even when the browser never returns. See Receiving webhooks.Refund your test payment
In the portal, open Once-Off Collections, find the E1.00 payment and refund it. A second person on your team approves the refund under Approvals before the money goes back.