Accept paymentsAvailable
Realtime updates
Show live payment status over a WebSocket without exposing a secret key.
Get a token
Create a realtime token from your server, or from the browser with a publishable key. Scope it to one invoice for customer-facing pages.
const response = await fetch(`${process.env.BOSPAY_API_BASE}/realtime/tokens`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"BOSPay-Version": "2026-09-23",
"X-API-Key": process.env.BOSPAY_API_KEY,
},
body: JSON.stringify({
"invoiceId": "inv_1048"
})
});
if (!response.ok) {
throw new Error(`BOSPay request failed: ${response.status}`);
}
const data = await response.json();Connect
Browser
const ws = new WebSocket(`wss://${apiHost}/ws?token=${token}`);
ws.onmessage = (message) => {
const event = JSON.parse(message.data);
// { type: "invoice-status", invoiceId, data: { status, txHash, confirmations, amountPaid } }
if (event.type === "invoice-status") render(event.data.status);
};Connect within 5 minutes; the socket stays open after the token expires. A token issued for an invoice subscribes to it automatically and cannot watch other invoices. An organization-wide token can send {"type":"subscribe","invoiceId":"inv_…"}.
Rules
- Never put an API key in a WebSocket URL: it is rejected, and URLs end up in logs.
- Server clients may send the key in the Authorization header instead of using a token.
- Realtime status is for display. Fulfill from a verified invoice.paid webhook.