Skip to main content
GET
/
ws
/
merchant
/
events
Merchant Monitor Stream (event_v1)
curl --request GET \
  --url https://api-beta.pepay.io/ws/merchant/events \
  --header 'x-api-key: <api-key>'

​
Overview

Use this WebSocket endpoint to receive realtime merchant events (for example: invoice updates, payments, and commerce order events where applicable).

​
Authentication

WebSocket connections use a token minted from the REST API. See: Mint a WebSocket Token.

​
Request

const stream = pepay.ws.connectMerchantEvents({ format: 'event_v1' });
stream.on('event', (event) => console.log(event));

​
WebSocket URL (wss)

WS_TOKEN="ws_..."

echo "wss://api-beta.pepay.io/ws/merchant/events?token=$WS_TOKEN"

​
Response

WebSocket upgrade returns 101 Switching Protocols. After connecting, you receive frames (for example event_v1 events). Example event frame: 
{
  "id": "evt_1734780000000-123",
  "object": "event",
  "api_version": "2025-12-16",
  "created": 1734780000,
  "type": "invoice.updated",
  "livemode": false,
  "pending_webhooks": 0,
  "data": {
    "object": {
      "object": "invoice",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "paid",
      "invoice_type": "standard",
      "environment": "devnet"
    }
  }
}

​
Errors

  • 401 invalid/expired ws_token (connection is rejected/closed)
  • Treat delivery as at-least-once; dedupe by event.id if you process idempotently.

​
Examples

  • Use since=<event_id> to resume from a known cursor when supported.
Next: Merchant Invoices

Authorizations

​
x-api-key
string
header
required

API key for server-to-server operations (scope=merchant or commerce)

Query Parameters

​
token
string

Short-lived ws_token (browser/mobile auth).

​
since
string

Replay cursor (event id), e.g. evt_1700000000000-123.

​
types
string

Comma-separated allowlisted event type filters (e.g. invoice.*, invoice_payment.updated).

​
invoice_type
string

Optional invoice type filter (e.g. standard, commerce).

​
customer_id
string
​
invoice_id
string
​
environment
enum<string>
Available options:
devnet,
mainnet
​
format
enum<string>
Available options:
event_v1

Response

101

Switching Protocols (WebSocket)