Authentication

​

Overview

​

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)

• x-session-token: pst_...
• x-signature: sig_...

​

WebSocket auth (browser/mobile)

• POST /api/v1/ws/token

• wss://.../ws/merchant/events?token=<ws_token>
• wss://.../ws/commerce/events?token=<ws_token>

​

Request

# 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_..."

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_..."

curl -X POST "${PEPAY_API_URL}/api/v1/ws/token" \
  -H "x-api-key: pk_..." \
  -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 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

{
  "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.