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
amountSzlout, optionally withminAmountSzlandmaxAmountSzl. 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
/payment-linksAPI keyBody parameters
namestringrequired | Up to 100 characters. The title payers see, e.g. "Term 1 fees". |
referencestringrequired | Up to 100 characters. Attached to every payment made on the link and shown on the MoMo prompt. |
descriptionstringoptional | Up to 500 characters, shown under the title. |
amountSzlstringoptional | Fixed amount. Leave out to let the payer choose. |
minAmountSzlstringoptional | Lowest amount a payer may enter. Not allowed with amountSzl. |
maxAmountSzlstringoptional | Highest amount a payer may enter. Not allowed with amountSzl. |
reusablebooleanoptional | Default true. false closes the link after one successful payment. |
expiresAtstringoptional | ISO 8601 time after which the link stops accepting payments. Must be in the future. |
{
"name": "Invoice 2291 — Mbabane Hardware",
"reference": "INV-2291",
"amountSzl": "1850.00",
"reusable": false,
"expiresAt": "2026-11-30T21:59:59.000Z"
}{
"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_Xy7Qm2Lp9Rt4WvNo 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
/payment-linksAPI keyAll your links, newest first, each with what it has brought in and whether it can be paid right now:
{
"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
/payment-links/:id/deactivateAPI keyStops the link accepting payments. Payments already made aren't affected.
{ "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.