Skip to main content

​
Overview

The SDK is configured once and exposes resource groups (invoices, tokens, commerce, events, websockets, etc.).

​
Authentication

The SDK supports multiple auth contexts (set once or per request). Choose the minimum required for your surface:
  • apiKey → x-api-key (merchant scope)
  • commerceApiKey → x-commerce-api-key (commerce scope)
  • bearerToken → Authorization: Bearer ... (dashboard JWT)
  • userAccessToken → User-Authorization: Bearer ... (commerce user routes)
  • sessionToken + signature → x-session-token + x-signature (payor/session browser-safe)

​
Request

​
Construct a client

import { Pepay } from 'pepay';

const pepay = new Pepay({
  baseUrl: process.env.PEPAY_API_URL ?? 'https://api-beta.pepay.io',
  apiKey: process.env.PEPAY_API_KEY
});

​
Switch auth context

const merchant = pepay.withAuth({ apiKey: process.env.PEPAY_API_KEY! });
const commerce = pepay.withAuth({ commerceApiKey: process.env.PEPAY_COMMERCE_API_KEY! });
If both keys are configured, the SDK selects the correct header per endpoint and never sends both headers.

​
Response

The configured client will automatically attach the correct headers and defaults: 
{
  "baseUrl": "https://api-beta.pepay.io",
  "auth": ["x-api-key"],
  "timeouts": { "timeoutMs": 30000 },
  "retries": { "maxRetries": 2, "retryableStatusCodes": [429, 500, 503] }
}

​
Errors

  • 401 auth missing/invalid: verify the credential you configured matches the endpoint (merchant vs commerce vs payor).
  • 403 forbidden: key may be scoped/suspended, or environment access may not be enabled.
  • Browser runtime error when using server keys: use session/ws tokens instead of server API keys.

​
Examples

​
Retries and timeouts

const pepay = new Pepay({
  apiKey: process.env.PEPAY_API_KEY!,
  timeoutMs: 30_000,
  maxRetries: 2,
  retryableStatusCodes: [429, 500, 503]
});

​
Browser safety

By default, the SDK rejects server API keys in browser runtimes. If you truly need to override this (not recommended), you must opt in: 
const pepay = new Pepay({
  allowServerKeysInBrowser: true,
  apiKey: 'sk_live_...'
});

​
WebSockets

WebSocket usage requires a webSocketFactory (browser provides WebSocket; Node.js typically uses ws). 
import WebSocket from 'ws';
import { Pepay } from 'pepay';

const pepay = new Pepay({
  apiKey: process.env.PEPAY_API_KEY!,
  baseUrl: process.env.PEPAY_API_URL ?? 'https://api-beta.pepay.io',
  webSocketFactory: WebSocket as any
});
Next: Invoices