Realtime#
Realtime pushes payment events to a browser or server over a WebSocket, the instant they happen. Use it to flip your checkout page from "Waiting for your transfer" to "Payment received" without polling and without the customer refreshing.
The socket carries exactly the same events and payloads as webhooks. The difference is who listens:
| Webhooks | Realtime | Polling | |
|---|---|---|---|
| Listener | Your server | A browser, app or server | Your code, on a timer |
| Delivery | Pushed, signed, retried for about 22 hours | Pushed while connected | Pulled |
| Best for | Fulfilling orders | Live checkout UX, ops dashboards | Scripts, fallbacks |
How it works#
Your server creates the transaction and a client token#
A client token (ct_…) is a short-lived credential that can only read one transaction. It expires after 30
minutes, so it's safe to send to the browser. Your secret key never leaves your server.
The browser subscribes#
The checkout page opens a socket with the client token and subscribes to the channel transaction:<id>. On
every (re)connection it receives the transaction's current state.
Yusr pushes events#
When the transfer arrives, the socket receives a transaction.paid event (or underpaid, overpaid, expired
and so on) within moments of the webhook being created.
Create a client token#
The API responds with 201 Created:
Create a token whenever you render the checkout page. If the customer is still on the page after 30 minutes, ask your server for a fresh one.
Use @yusr/js in the browser#
@yusr/js is a small browser library that handles the socket for you: it connects, subscribes,
reconnects with backoff and re-subscribes, and always hands you the latest state.
Drop-in payment widget#
renderPaymentWidget renders an accessible "Pay by bank transfer" card with copy buttons, an expiry countdown
and a live status that switches to Payment received when the money arrives.
Here is a complete checkout page. Your server renders it with the transaction and a fresh client token:
Theme the widget with CSS variables such as --yusr-accent and --yusr-radius, or hide it and build
your own UI with the subscription below. Displaying payment details has layout guidance for
custom designs.
Your own UI#
subscribeToTransaction gives you the state and events and leaves rendering to you.
Listen on your server#
A server can subscribe with its secret key, either to one transaction or to the merchant channel, which
receives every event for your account in that mode. This is handy for an internal operations screen or a
point-of-sale display.
Protocol reference#
Realtime runs on Socket.IO (protocol v4), so any Socket.IO client works. Use this reference
to integrate without @yusr/js.
Connect#
| Setting | Value |
|---|---|
| URL | The API origin, wss://api.<your domain> (no /v1 in the URL) |
Socket.IO path | /v1/realtime |
transports | ["websocket"] |
auth | { "token": "<client token or secret key>" } |
A client token (ct_…) can subscribe only to its own transaction. A secret key (sk_test_… or sk_live_…) can
subscribe to any transaction and to merchant, and must only be used from servers. An invalid or expired token
fails the handshake with a connect_error whose message is authentication_failed. Each account can hold up to
500 open connections; beyond that, new connections fail with rate_limited.
Subscribe#
Emit subscribe with a channel and an acknowledgement callback:
| Channel | Who may subscribe | Receives |
|---|---|---|
transaction:<id> | Client token for that transaction, or a secret key | Events for one transaction |
merchant | Secret key only | Every event for the account, in the key's mode |
A successful acknowledgement for a transaction channel includes the current transaction:
(The transaction field holds the complete transaction object; it's shortened here.) For merchant the
acknowledgement is { "ok": true, "channel": "merchant" }. Failures look like this:
| Error code | Cause |
|---|---|
permission_denied | A client token tried to subscribe to merchant or to another transaction. |
invalid_request | The channel isn't merchant or transaction:<id>. |
not_found | No such transaction for this account and mode. |
internal_error | Temporary failure. Retry the subscription. |
To stop receiving a channel, emit unsubscribe with { "channel": "…" }; the acknowledgement is
{ "ok": true }.
Receive events#
The server emits event with a payload identical to the webhook body:
Events are not signed on the socket, because the connection itself is authenticated. Deduplicate by id if you
act on them, as you would with webhooks.
Connection lifecycle#
- The server pings every 25 seconds; Socket.IO clients answer automatically. Dead connections are dropped.
- After a reconnect, subscribe again. The acknowledgement carries the latest state, which covers any event you missed while disconnected.
- When a client token expires, the next connection attempt fails with
authentication_failed. Fetch a new token from your server and reconnect. - Close the socket when the customer leaves the checkout page.
Testing realtime in the sandbox#
Open your checkout page with a test transaction, then simulate a payment from the dashboard or the API. The page receives the same event a real transfer would produce.