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
- You call
POST /collections. Nodal sends the prompt and answers202with statusINITIATED. - The customer approves (or declines, or ignores) the prompt on their phone.
- The collection ends
COMPLETEDorFAILED. You hear about it through thecollection.completedorcollection.failedwebhook, or by fetching it.
Most customers respond within a minute. Show "Check your phone to approve the payment" while you wait.
Create a collection
/collectionsAPI key · Idempotency-Key recommendedBody parameters
msisdnstringrequired | Customer's MoMo number, e.g. 26876123456. |
amountSzlstringrequired | Amount, e.g. "250.00". |
referencestringrequired | Up to 100 characters. Appears on the MoMo prompt and in your reports, e.g. "Invoice 2291". |
providerstringoptional | Wallet provider. Default and only option today: mtn_momo. |
<?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{
"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:
{
"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
/collections/:idAPI key{
"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
/collectionsAPI keyEvery 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.
GET /collections?status=COMPLETED&from=2026-10-01&to=2026-10-31&limit=100Webhooks
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.