Skip to content
YusrDocs

Polling#

Polling means asking the API for a transaction's status on a timer with GET /v1/transactions/{id}. It is the simplest way to wait for a payment, but it's also the slowest and least efficient. Use it as a fallback:

  • when a webhook is late and a customer is waiting on the checkout page;
  • in scripts, back-office tools and tests where running a webhook endpoint is impractical;
  • to double-check a transaction's state before a sensitive action, such as releasing high-value goods.

For everything else, webhooks (server) and realtime (browser) are faster and don't use your rate limit.

The rules#

RuleValue
Recommended intervalEvery 5 seconds
Hard limit1 request per second per transaction (short bursts of 2 are tolerated)
Above the limit429 rate_limited with Retry-After: 1
Stop whenThe status is no longer pending (see When to stop)
Give up atpayment.expires_at, plus a short grace period

The per-transaction limit applies on top of your account-wide rate limit of 25 requests per second. Polling hundreds of open transactions every second will exhaust it, so don't.

JSON
{
  "error": {
    "code": "rate_limited",
    "message": "Poll at most once per second per transaction (5 s recommended).",
    "request_id": "req_01M47EGND4WSYF7MKK2M409K7C"
  }
}

Poll a transaction#

The Node.js library has a built-in helper, waitForPayment, that follows all of these rules: a 5-second interval, waiting out 429 responses for the Retry-After period, and continuing through transient network and 5xx errors.

#!/usr/bin/env bash
# Poll every 5 seconds until the transaction leaves "pending" (requires jq).
TXN=txn_01JA9Q3K7M2V8X4N6P0R2T5W7Y
while true; do
  STATUS=$(curl -s https://api.yusr.ng/v1/transactions/$TXN \
    -H "Authorization: Bearer $YUSR_SECRET_KEY" | jq -r '.status')
  echo "status: $STATUS"
  [ "$STATUS" != "pending" ] && break
  sleep 5
done

Back off on errors#

When a poll fails, slow down rather than retrying straight away:

  • 429 rate_limited: wait at least the number of seconds in the Retry-After header.
  • 5xx or network errors: retry with exponential backoff (for example 5 s, 10 s, 20 s… up to 60 s), plus a random jitter of up to a second so many clients don't retry in lockstep.
  • 401, 403 or 404: don't retry. Fix the key or the transaction ID. Remember that test transactions aren't visible to live keys.

When to stop#

Stop polling as soon as the status is anything other than pending, and act on it:

StatusAction
paid, overpaidFulfil the order.
underpaidTell the customer how much is missing. The account still accepts a top-up until payment.expires_at, so keep polling (or listening) until then if you accept top-ups.
expired, cancelledStop. If money arrives later, the transaction becomes late_payment and you get a webhook.
failedStop and create a new transaction.
late_payment, reversedStop and follow your process for these cases.

Also stop when payment.expires_at has passed: a pending transaction becomes expired at that moment. Allow a grace period of a minute or two for the status to update.

Find a transaction by your reference#

If you only stored your own reference (for example after a crash between creating the transaction and saving its ID), look it up with the reference filter.

curl -G https://api.yusr.ng/v1/transactions \
  -H "Authorization: Bearer $YUSR_SECRET_KEY" \
  --data-urlencode "reference=order-1042"

The response is a list with zero or one transaction, because references are unique per account and mode.

Polling from a browser#

Never poll the Yusr API from a browser: it would need your secret key. If your checkout page needs live status without a socket, have the page poll your own server, and let your server read its database (updated by webhooks), falling back to GET /v1/transactions/{id} at most every 5 seconds. Better still, use realtime with a client token.