Skip to content

Retries and reconciliation

The result callback is sent once for each terminal status a transaction reaches, on a best-effort basis. Most transactions reach one, so most get one callback. A payment that succeeds and is later reversed reaches two (SUCCESS, then REVERSED) and gets a callback for each.

You have two ways to find out how a transaction ended up. Use both.

  • Push: the result callback. Pesepay posts the final status to the resultUrl you set when you created the transaction, as soon as the customer finishes or the transaction times out. It is the quickest way to hear about a payment. See The result callback.
  • Pull: a status check. Call Check Payment Status with the transaction’s referenceNumber whenever you need its current state: to confirm a callback before you act on it, to show a “checking your payment” state on your returnUrl page, and to sweep pending transactions in a reconciliation job.

The pollUrl in the initiate and make-payment responses points at the same status check, scoped to that transaction; either works. transactionStatus is one of a fixed set of values; see transaction statuses for which are terminal (safe to stop checking) and which are still in progress.

  1. Return 2xx fast. Acknowledge the callback, then do fulfilment, emails, and invoicing asynchronously. A handler that takes seconds is a handler that times out.

  2. Reconcile on a schedule. Run a job that finds every order still awaiting payment after a reasonable window — a few minutes is usually enough — and calls Check Payment Status for each one. This is what catches the transactions whose callback never landed.

  3. Stop only on a terminal status. Keep checking until transactionStatus is terminal. PENDING, PROCESSING, and PARTIALLY_PAID all mean the payment is still in flight.

  4. Age out abandoned attempts. Customers walk away from checkouts. Give an unpaid transaction a sensible expiry in your own system rather than polling it forever.

  5. Keep the handler idempotent. Your callback handler and your reconciliation job will sometimes process the same result. Key both on referenceNumber — see Verifying callbacks.

Because there’s no retry, a callback that arrives mid-deploy is simply gone. Two things make that a non-event: reconciliation, and never treating “no callback” as “no payment”. Anything you’d have done from the callback should be reachable from the reconciliation path too.

Run this on a schedule. It calls the same settle function as your callback handler, so a payment settles exactly once whichever path finds it first.

jobs/reconcile.js
// Every 5 minutes.
async function reconcile() {
const stale = await orders.findUnpaidOlderThan({ minutes: 5 });
for (const order of stale) {
const result = await pesepay.checkPayment(order.referenceNumber);
if (!result.success) continue; // transient — try again next run
if (result.paid) {
await orders.markPaid(order.id);
await fulfil(order);
} else if (order.createdAt < hoursAgo(24)) {
await orders.expire(order.id); // the customer never came back
}
}
}