WS token

Overview

ws_token is a short-lived JWT used to authenticate websocket streams from browser/mobile contexts without exposing long-lived API keys. It is not required for server-to-server connections that can send API key headers. Note: ws_token is only for merchant/commerce streams. Payor streams use the payment session token.

Authentication

Minting requires server-to-server auth:

x-api-key (merchant)
x-commerce-api-key (commerce)

Request

Endpoint:

POST /api/v1/ws/token

Playground (interactive reference):

Mint a WebSocket token

Example:

BASE_URL=${PEPAY_API_URL}

curl -X POST "$BASE_URL/api/v1/ws/token" \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"scope":"merchant"}'

Response

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "scope": "merchant",
    "merchant_id": 123,
    "network_environment": null,
    "expires_at": 1766320496,
    "ws_url": "wss://api-beta.pepay.io/ws/merchant/events"
  }
}

Errors

401 invalid API key
400 invalid scope/ttl

Examples

Use the returned data.token as ?token=<ws_token> when connecting to /ws/merchant/events or /ws/commerce/events from browser/mobile clients.

Next: WebSockets

Overview

API

Merchant

Tokens

Commerce

Payor

WebSockets

Webhooks

Overview

Authentication

Request

Response

Errors

Examples

​Overview

​Authentication

​Request

​Response

​Errors

​Examples

Overview

Authentication

Request

Response

Errors

Examples