Skip to main content

​
Overview

Pepay supports multiple auth modes depending on the surface area (merchant, commerce, payor/session) and whether the request is server-side or browser-side. If you’re getting started, log in to the Dashboard to obtain API keys: .

​
Authentication

​
Server-to-server (merchant + commerce)

  • Merchant API key: x-api-key: pk_... (scope=merchant)
  • Commerce API key: x-commerce-api-key: ck_... (scope=commerce)
  • Dashboard JWT (for key-management endpoints): Authorization: Bearer <jwt>

​
Browser-safe (payor/session)

Payor session endpoints use:
  • x-session-token: pst_...
  • x-signature: sig_...

​
WebSocket auth (browser/mobile)

For websocket streams in client contexts, mint a short-lived ws_token server-to-server:
  • POST /api/v1/ws/token
Then connect using:
  • wss://.../ws/merchant/events?token=<ws_token>
  • wss://.../ws/commerce/events?token=<ws_token>

​
Request

Example (merchant API key): 
# Set your API URL (default: https://api-beta.pepay.io)
export PEPAY_API_URL="https://api-beta.pepay.io"

curl "${PEPAY_API_URL}/api/v1/invoices?limit=1" \
  -H "x-api-key: pk_..."
Example (payor/session headers): 
curl "${PEPAY_API_URL}/api/v1/payments/payment-status?invoice_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "x-session-token: pst_..." \
  -H "x-signature: sig_..."
Example (mint a ws_token): 
curl -X POST "${PEPAY_API_URL}/api/v1/ws/token" \
  -H "x-api-key: pk_..." \
  -H "Content-Type: application/json" \
  -d '{"scope":"merchant"}'

​
Response

Authentication is not a standalone endpoint — response shapes depend on the route you call. Below is a representative success response from POST /api/v1/ws/token. 
{
  "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

Common causes:
  • 401 missing or invalid credentials
  • 403 wrong auth mode for the endpoint (for example, using x-api-key where x-session-token is required)
  • 400 invalid signatures or invalid request bodies
Example (invalid API key): 
{
  "success": false,
  "error": {
    "code": "API_KEY_INVALID",
    "message": "Invalid API key"
  }
}

​
Examples

  • Do not send x-api-key or x-commerce-api-key from browsers.
  • If you need client-side access, use payment sessions (x-session-token + x-signature) or mint a ws_token server-side.
Next: Rate limits