Skip to main content

​
Overview

Payor websocket streams are used for checkout UX updates. They are scoped to a single payment session and emit payor-safe updates.

​
Authentication

Payor websocket auth uses a payment session token via the token query param. This token is returned when you create an invoice and is safe to use in the client during checkout. Notes:
  • format=event_v1 returns canonical PepayEvent frames (recommended).
  • The SDK payor stream does not include REST backfill; treat it as realtime only.

​
Request

​
Connect to the payor stream

const ws = pepay.ws.connectPaymentSession({ token: process.env.PEPAY_PAYMENT_SESSION_JWT!, format: 'event_v1' });

ws.on('message', (message) => {
  console.log('message', message);
});

​
Response

Example frame (event_v1): 
{
  "id": "evt_1734780000000-123",
  "object": "event",
  "created": 1734780000,
  "type": "payment_quote.updated",
  "data": {
    "object": {
      "object": "payment_quote",
      "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
      "network": "base",
      "currency": "usd",
      "amount_remaining": 49990,
      "amount_remaining_decimal": "49.990",
      "amount_unit": "usd_millis"
    }
  }
}

​
Errors and delivery

  • Invalid/expired session token: connection is rejected/closed by the server.
  • Delivery is at-least-once; render UI updates idempotently.
  • If you need a replay, reconnect with since=<event_id> (event_v1 only).

​
Underpaid lock-in

If a partial payment is received, the invoice status becomes underpaid. Fetch session details to read:
  • locked_network
  • locked_token_id
  • locked_payment_address
Payors must complete the remaining balance using the locked network/token.

​
Examples

  • Prefer format=event_v1 when available so you can reuse the same event parsing across merchant + payor streams.
Next: API Spec overview