Skip to main content

​
Overview

Use the commerce WebSocket stream for realtime commerce.order.* updates and linked commerce invoice/payment context. It emits the same event types as the commerce webhooks, but with replay and REST backfill for resilience. Commerce invoices expire after ~30 minutes; include invoice.* if you want to capture invoice.updated with status=expired.

​
Authentication

The SDK connects via query params, so use a short-lived ws_token minted server-side. WebSocket headers (for direct x-commerce-api-key auth) are supported by the raw endpoint but are not wired into the SDK today.

​
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

Example commerce event frame: 
{
  "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

connectCommerceEvents returns a PepayEventStream that:
  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.
Delivery is at-least-once; dedupe by event.id.

​
Devnet simulator

Devnet order simulation (commerce.devnet.simulateOrder) emits the same commerce.order.updated events on this stream. See Orders for the simulation flow.

​
Examples

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