Skip to main content
This page documents the security posture that’s relevant for integrators: what belongs on your server, what is safe in the browser, and how to avoid common mistakes.

​
Key handling

  • Never ship server API keys (x-api-key, x-commerce-api-key) to browsers.
  • Use server-to-server auth for privileged merchant/commerce operations.
  • Treat API keys as secrets: store them in environment variables or a secret manager, rotate regularly, and avoid logging them.

​
Browser-safe auth (payor flows)

Payor/session routes use browser-safe auth headers:
  • x-session-token
  • x-signature
For realtime in browsers/mobile, use a short-lived ws_token minted server-to-server and passed as a websocket query param.

​
SDK safety defaults

Pepay SDK is designed to be safe-by-default in browser contexts:
  • By default, the SDK rejects server API keys in browser runtimes.
  • Use session tokens / ws tokens for client-side integrations.

​
Idempotency and retries

Network failures happen. Use a consistent strategy:
  • Writes should include an Idempotency-Key (the SDK auto-generates one by default).
  • Retries should respect Retry-After on rate limits.
  • Prefer a single canonical “Errors” page and link to it from every endpoint page.
Next: Get started