WebSockets (merchant)

​

Overview

​

Authentication in the SDK

​

Request

​

Mint a ws_token

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

​

Connect to merchant events

const stream = pepay.ws.connectMerchantEvents({
  token: String(token?.data?.token),
  format: 'event_v1',
  types: 'invoice.*,invoice_payment.*'
});

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

​

Filters you can pass

• types: Comma-separated event types (supports wildcards, e.g. invoice.*).
• invoice_type: Optional invoice type filter.
• invoice_id: Scope to a single invoice.
• customer_id: Scope to a merchant customer.
• environment: devnet or mainnet.
• format: event_v1 (recommended).

​

Common use cases

• Merchant dashboards: types=invoice.*,invoice_payment.* with optional environment filter.
• Single-invoice UI: pass invoice_id to reduce noise.
• Commerce order tracking: use the commerce stream with types=commerce.order.* and optional order_id.

​

Commerce stream (order lifecycle)

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

​

Response

{
  "id": "evt_1734780000000-123",
  "object": "event",
  "created": 1734780000,
  "type": "invoice.updated",
  "data": {
    "object": {
      "object": "invoice",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "paid"
    }
  }
}

​

Errors

• 401/403 when token or API-key auth is invalid.
• 400 when query filters are malformed.
• Network disconnects are expected; reconnect and resume with since=<last_event_id>.

​

Event frames and delivery

• object=event: business events (PepayEvent).
• object=ws_control: replay/resync hints (listen via stream.on('control')).
• object=ws_error: terminal error (connection closes).
• Delivery is at-least-once; dedupe by event.id.

​

Relationship to webhooks

• Merchant WebSockets deliver the same event types as merchant webhooks.
• The WebSocket stream includes replay + REST backfill, making it more redundant and reliable than webhooks for realtime consumption.
• Webhooks remain best for server-to-server side effects and audit trails.

​

Recovery and backfill

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

• Recovery is disabled if no API key is available. To force it, pass recovery.request.auth with the appropriate key.
• Use connectMerchantEventsRaw or connectCommerceEventsRaw if you want raw websockets without REST backfill.

​

SDK configuration

• webSocketFactory is required outside the browser (use ws in Node).
• websocketBaseUrl overrides the default ws URL.
• wsHeartbeatMs, wsIdleTimeoutMs, and wsPingMessage control liveness behavior.
• retry controls reconnect backoff.

​

Examples

• Persist the last seen event.id in durable storage so you can resume after deploys/restarts.