⬡ Nodal Docs

Direct collections

Charge a customer's MoMo wallet from your own screen: you collect their number, your server asks Nodal to send the payment prompt to their phone, and the customer approves it with their PIN.

Use this when you want the whole experience inside your app or at a till. If you just want customers to pay online, hosted checkout is less work.

How it works

  1. You call POST /collections. Nodal sends the prompt and answers 202 with status INITIATED.
  2. The customer approves (or declines, or ignores) the prompt on their phone.
  3. The collection ends COMPLETED or FAILED. You hear about it through the collection.completed or collection.failed webhook, or by fetching it.

Most customers respond within a minute. Show "Check your phone to approve the payment" while you wait.

Create a collection

POST/collectionsAPI key · Idempotency-Key recommended

Body parameters

msisdnstringrequiredCustomer's MoMo number, e.g. 26876123456.
amountSzlstringrequiredAmount, e.g. "250.00".
referencestringrequiredUp to 100 characters. Appears on the MoMo prompt and in your reports, e.g. "Invoice 2291".
providerstringoptionalWallet provider. Default and only option today: mtn_momo.
Create a collection
<?php
$ch = curl_init("https://api.tfolanodal.com/collections");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("NODAL_API_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: invoice-2291",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "msisdn"    => "26876123456",
        "amountSzl" => "250.00",
        "reference" => "Invoice 2291",
    ]),
]);
$collection = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE); // 202 = prompt sent
202 Accepted
{
  "id": "col_8fK2mQ9xLp",
  "status": "INITIATED",
  "amountSzl": "250.00",
  "currency": "SZL",
  "providerReference": "6a1f0c2e-3b8d-4f61-9a57-0e2b7c4d9f10",
  "correlationId": "c0b4…",
  "message": "Payer has been prompted. Final status will be confirmed by poll."
}

If MTN refuses the request outright (for example, an unknown number), the collection fails immediately:

502 Bad Gateway
{
  "error": "Collection rejected by provider",
  "id": "col_8fK2mQ9xLp",
  "status": "FAILED",
  "reason": "…"
}

A timeout is not a failure

Sometimes MTN doesn't confirm it received the request. Nodal then still answers 202 INITIATED, with a message saying the customer may have been prompted. Don't retry with a new key and don't ask the customer to pay again — wait for the final status. Nodal keeps checking with MTN until it knows.

Get a collection

GET/collections/:idAPI key
200 OK
{
  "id": "col_8fK2mQ9xLp",
  "msisdn": "26876123456",
  "amountSzl": "250.00",
  "currency": "SZL",
  "reference": "Invoice 2291",
  "status": "COMPLETED",
  "provider": "mtn_momo",
  "providerReference": "6a1f0c2e-3b8d-4f61-9a57-0e2b7c4d9f10",
  "mandateId": null,
  "repeatingRequestId": null,
  "paymentLinkId": null,
  "checkoutSessionId": null,
  "createdAt": "2026-10-23T08:15:00.000Z",
  "completedAt": "2026-10-23T08:15:41.000Z",
  "failedAt": null,
  "failureReason": null,
  "...": "..."
}

mandateId, repeatingRequestId, paymentLinkId and checkoutSessionId say where a payment came from: a mandate debit, a repeating request, a payment link or a checkout session. All four are null for a direct collection. The response may include more internal fields; rely only on the ones documented here.

List collections

GET/collectionsAPI key

Every payment into your wallet — direct, checkout, payment link and mandate debits — newest first. Supports page, limit, status, search, from and to; see Lists and pagination.

HTTP
GET /collections?status=COMPLETED&from=2026-10-01&to=2026-10-31&limit=100

Webhooks

collection.initiated, collection.completed, collection.failed, collection.unresolved and collection.refunded. These fire for every collection, including checkout, payment link and mandate payments. See the event reference.