⬡ Nodal Docs

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.
  1. 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 example NODAL_API_KEY), never in your code, a web page or a mobile app.

  2. Create a checkout session

    When the customer clicks "Pay", your server creates a session for the order. Send an Idempotency-Key that is unique to the order, so a retried request can never create a second session.

    Create a 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 id and the url of its payment page:

    201 Created
    {
      "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 id against the order: you need it to confirm the payment.

  3. 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 successUrl with the session id added:

    https://shop.example.com/orders/1042/paid?checkout_session_id=cs_V1StGXR8Z5jdHi6BmyT2kq0A
  4. Confirm 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 status is completed:

    Confirm a session
    <?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.completed so your server hears about every payment, even when the browser never returns. See Receiving webhooks.

  5. 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.