Follow payments
Checking a payment
Ask for a payment every 30 seconds until it settles. Webhooks are optional.
GET
/v1/transactions/external/{externalReference}Signed · readGET
/v1/transactions/{reference}Signed · readBy your own external_reference (easiest: you already have it) or by TukuPay's reference.
The rules
- Every 30 seconds, no faster. Faster checks do not make M-Pesa answer sooner and count against your rate limit.
- Stop when
statusis no longerpending. - After 10 minutes still
pending: stop the loop, keep the order open, and check again later (once an hour is plenty). Do not send a new prompt for the same order without checking first. - Check from your server, never from the payer's browser.
import { TukuPay } from "@tukupay/sdk";
const tukupay = new TukuPay();
// Check every 30 seconds; give up after 10 minutes and look again later (or ask the payer).
export async function waitForPayment(externalReference) {
for (let i = 0; i < 20; i++) {
const p = await tukupay.transactions.getByExternalReference(externalReference);
if (p.status !== "pending") return p; // completed, failed, awaiting_approval or reversed
await new Promise((r) => setTimeout(r, 30_000));
}
return null; // still pending: keep the order open and check again later
}| status | Meaning | Do |
|---|---|---|
pending | Sent; waiting for the payer or the network | Check again in 30 seconds |
completed | Done. The money moved | Hand over the goods; mark the order paid |
failed | Did not go through: see failure_reason (also a declined or expired approval) | Tell the payer; they can try again with a new external_reference |
awaiting_approval | Money out waiting for the account holder's PIN in TukuPay (see approval) | Wait; check again later |
reversed | Completed, then reversed | Treat as not paid |
approval, when there is one: { id, status (pending, approved, declined, expired), reasons, expires_at, decided_at }.
Or let TukuPay tell you
Webhooks arrive the moment a payment settles. If you use them, keep a slow check as a safety net (for example every 30 seconds for pending orders older than 2 minutes) in case your server was down when the webhook came.