Skip to main content

​
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): 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": "2025-12-21T12:34:56.000Z",
    "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