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#
| Rule | Value |
|---|---|
| Recommended interval | Every 5 seconds |
| Hard limit | 1 request per second per transaction (short bursts of 2 are tolerated) |
| Above the limit | 429 rate_limited with Retry-After: 1 |
| Stop when | The status is no longer pending (see When to stop) |
| Give up at | payment.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.
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.
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 theRetry-Afterheader.5xxor 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,403or404: 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:
| Status | Action |
|---|---|
paid, overpaid | Fulfil the order. |
underpaid | Tell 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, cancelled | Stop. If money arrives later, the transaction becomes late_payment and you get a webhook. |
failed | Stop and create a new transaction. |
late_payment, reversed | Stop 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.
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.