WebSockets (commerce)

​

Overview

​

Authentication

​

Request

​

Mint a ws_token

const token = await pepay.ws.token.mint({ scope: 'commerce', ttlSeconds: 60 });

​

Connect to commerce events

const stream = pepay.ws.connectCommerceEvents({
  token: String(token?.data?.token),
  format: 'event_v1',
  types: 'commerce.order.*'
});

stream.on('event', (event) => {
  console.log('event', event.id, event.type);
});

​

Filters you can pass

• types: Comma-separated event types (supports wildcards, e.g. commerce.order.*).
• order_id: Scope to a single order.
• invoice_id: Scope to a linked invoice.
• customer_id: Scope to a merchant customer.
• wallet_address: Scope to a payer wallet.
• wallet_network: Scope to a network (e.g. solana, bsc).
• format: event_v1 (recommended).

​

Response

{
  "id": "evt_1734780000000-456",
  "object": "event",
  "type": "commerce.order.updated",
  "created": 1734780000,
  "data": {
    "object": {
      "object": "commerce_order",
      "id": "order_123",
      "status": "fulfilled",
      "invoice_id": "inv_123"
    }
  }
}

​

Errors

• Token mint/connect auth failures return 401/403.
• Invalid stream query params return 400.
• Retry and resume from last event.id on transient disconnects.

​

Relationship to webhooks

• Webhooks and WebSockets deliver the same commerce.order.* event types.
• WebSockets include replay + REST backfill, so they are more resilient for realtime UX.
• Webhooks remain best for server-to-server side effects and audit trails.

​

Recovery and delivery

1. Replays from since=<last_event_id> on reconnect.
2. Backfills missed events via REST (/api/v1/events).
3. Buffers WS frames during backfill and emits in order.

​

Devnet simulator

​

Examples

• Keep the last delivered event.id and reconnect with since=<event_id> to avoid gaps after restarts.