⬡ Nodal Docs

Payment links

A payment link is a page anyone can pay on — share it by WhatsApp, SMS, email or a QR code. Use it for school fees, donations, invoices or a fixed-price product, with no website needed.

Most businesses create links in the portal under Payment Links. The API lets you create them from your own system, for example one link per invoice.

Kinds of link

  • Fixed amount — set amountSzl. The payer can't change it.
  • Payer chooses the amount — leave amountSzl out, optionally with minAmountSzl and maxAmountSzl. Without bounds, payers can pay E1.00 to E50,000.00.
  • Reusable (default) — anyone can pay any number of times. Single use (reusable: false) — closes after its first successful payment.

Create a link

POST/payment-linksAPI key

Body parameters

namestringrequiredUp to 100 characters. The title payers see, e.g. "Term 1 fees".
referencestringrequiredUp to 100 characters. Attached to every payment made on the link and shown on the MoMo prompt.
descriptionstringoptionalUp to 500 characters, shown under the title.
amountSzlstringoptionalFixed amount. Leave out to let the payer choose.
minAmountSzlstringoptionalLowest amount a payer may enter. Not allowed with amountSzl.
maxAmountSzlstringoptionalHighest amount a payer may enter. Not allowed with amountSzl.
reusablebooleanoptionalDefault true. false closes the link after one successful payment.
expiresAtstringoptionalISO 8601 time after which the link stops accepting payments. Must be in the future.
Request
{
  "name": "Invoice 2291 — Mbabane Hardware",
  "reference": "INV-2291",
  "amountSzl": "1850.00",
  "reusable": false,
  "expiresAt": "2026-11-30T21:59:59.000Z"
}
201 Created
{
  "id": "lnk_Xy7Qm2Lp9Rt4Wv",
  "name": "Invoice 2291 — Mbabane Hardware",
  "description": null,
  "amountSzl": "1850.00",
  "minAmountSzl": null,
  "maxAmountSzl": null,
  "reference": "INV-2291",
  "reusable": false,
  "isActive": true,
  "usageCount": 0,
  "expiresAt": "2026-11-30T21:59:59.000Z",
  "createdAt": "2026-10-23T08:15:00.000Z",
  "...": "..."
}

The link's page is at:

https://app.tfolanodal.com/pay/lnk_Xy7Qm2Lp9Rt4Wv

No idempotency on links

POST /payment-links doesn't accept an Idempotency-Key, so a retried request creates a second link. If a create times out, list your links and look for the reference before trying again.

Validation errors on this endpoint use a different shape from the rest of the API: { "error": "Invalid payload", "details": { … } }.

List links

GET/payment-linksAPI key

All your links, newest first, each with what it has brought in and whether it can be paid right now:

200 OK
{
  "data": [
    {
      "id": "lnk_Xy7Qm2Lp9Rt4Wv",
      "name": "Invoice 2291 — Mbabane Hardware",
      "reference": "INV-2291",
      "payments": 1,
      "collectedSzl": "1850.00",
      "state": "used",
      "...": "..."
    }
  ]
}

state is open, used (a single-use link that has been paid), expired or deactivated. This list isn't paginated.

Deactivate a link

POST/payment-links/:id/deactivateAPI key

Stops the link accepting payments. Payments already made aren't affected.

200 OK
{ "id": "lnk_Xy7Qm2Lp9Rt4Wv", "isActive": false }

Knowing when a link is paid

Each payment on a link is a collection with the link's reference and its paymentLinkId. Subscribe to collection.completed and match on reference — webhook payloads include the reference but not the link id, so give each link its own reference. You can also fetch the collection and read its paymentLinkId.

If someone reloads the page while a payment is in progress, they see that payment rather than being asked to pay again.