TukuPay Docs

Follow payments

Checking a payment

Ask for a payment every 30 seconds until it settles. Webhooks are optional.

GET/v1/transactions/external/{externalReference}Signed · read

SeeSigning requestsKeys and scopesErrors

GET/v1/transactions/{reference}Signed · read

SeeSigning requestsKeys and scopesErrors

By 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 status is no longer pending.
  • 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
}
statusMeaningDo
pendingSent; waiting for the payer or the networkCheck again in 30 seconds
completedDone. The money movedHand over the goods; mark the order paid
failedDid 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_approvalMoney out waiting for the account holder's PIN in TukuPay (see approval)Wait; check again later
reversedCompleted, then reversedTreat 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.