> ## Documentation Index
> Fetch the complete documentation index at: https://docs-alpha.pepay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSockets (payor)

> Connect to payor session websocket updates.

## 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` is the only supported format and returns canonical `PepayEvent` frames.
* The SDK payor stream does not include REST backfill; treat it as realtime only.

## Request

### Connect to the payor stream

```ts theme={null}
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):

```json theme={null}
{
  "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>`.

## 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

* `format=event_v1` matches merchant/commerce parsing so you can reuse event handlers across streams.

Next: [API Spec overview](/api-spec/overview)