Skip to main content

​
Overview

Pepay’s API is organized around three surfaces plus event delivery:
  • Merchant API: invoices, settlement, tokens, events, and account-level operations.
  • Commerce API: product search, merchant carts, checkout, orders, and payments.
  • Payor API: session-scoped checkout reads and payment status updates.
  • WebSockets: realtime events for merchant and commerce workflows.
  • Webhooks: server-to-server event delivery for durable processing.
This reference covers the public endpoints intended for production integrations; internal/admin routes are intentionally omitted.

​
Base URLs and environments

  • Base URL selects the deployment. Default used in examples: {DEFAULT_BASE_URL}.
  • Environment (environment=devnet|mainnet) selects the network context for endpoints that support it.
  • Devnet uses full testnet rails. Mainnet access must be enabled for your account before production use.

​
Devnet commerce status updates

For testnet commerce flows, use the devnet simulator endpoint to advance order status transitions. It emits the same commerce.order.* events you receive via WebSockets and webhooks, so you can test end-to-end behavior without real orders.

​
Authentication

Pepay supports multiple auth modes depending on surface area (merchant vs commerce vs payor). See: Authentication.

​
Realtime delivery: WebSockets vs Webhooks

ChannelBest forReliability notes
WebSocketsLive UI updates and realtime dashboardsIncludes replay/backfill; events are at-least-once so dedupe by event.id.
WebhooksServer-side side effects and audit trailsRetries on non-2xx; events are at-least-once so dedupe by event.id or X-Pepay-Event-ID.
We recommend using both for resilience: WebSockets for realtime UX, Webhooks for durable processing.

​
Request

To use these examples, first set your environment variable: 
# Set your API URL (default: https://api-beta.pepay.io)
export PEPAY_API_URL="https://api-beta.pepay.io"
Example request (list invoices): 
curl "${PEPAY_API_URL}/api/v1/invoices?limit=1" \
  -H "x-api-key: sk_live_..."

​
Response

List response envelope: 
{
  "object": "list",
  "data": [],
  "has_more": false
}

​
Errors

  • 401/403 auth errors (wrong header type, invalid token, or insufficient scope)
  • 429 rate limits (respect Retry-After)
  • 5xx transient server errors (retry with backoff where safe)
See: Errors. Next: Authentication