> ## Documentation Index
> Fetch the complete documentation index at: https://docs-alpha.pepay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Base URLs, environments, request conventions, and how this reference is scoped.

## 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: `https://api-beta.pepay.io`.
* **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](/api-spec/authentication).

## Realtime delivery: WebSockets vs Webhooks

| Channel    | Best for                                  | Reliability notes                                                                           |
| ---------- | ----------------------------------------- | ------------------------------------------------------------------------------------------- |
| WebSockets | Live UI updates and realtime dashboards   | Includes replay/backfill; events are at-least-once so dedupe by `event.id`.                 |
| Webhooks   | Server-side side effects and audit trails | Retries 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:

```bash theme={null}
# Set your API URL (default: https://api-beta.pepay.io)
export PEPAY_API_URL="https://api-beta.pepay.io"
```

Example request (list invoices):

```bash theme={null}
curl "${PEPAY_API_URL}/api/v1/invoices?limit=1" \
  -H "x-api-key: sk_live_..."
```

## Response

List response envelope:

```json theme={null}
{
  "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](/api-spec/errors).

## Examples

* Merchant server request:

```bash theme={null}
curl "${PEPAY_API_URL}/api/v1/invoices?limit=5" \
  -H "x-api-key: pk_live_..."
```

Next: [Authentication](/api-spec/authentication)