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

# How It Works

> A high-level view of Pepay flows for merchants, commerce, and payors.

Pepay integrations typically have two surfaces: a **merchant server** that creates and controls payment objects, and a **payor client** that renders checkout and reads session-scoped data safely.

## Integration surfaces

| Surface               | Runs where                     | Responsible for                                                                           | Auth model                           |
| --------------------- | ------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------ |
| **Merchant (server)** | Your backend                   | Create invoices, manage commerce operations, mint session/WS tokens, reconcile settlement | API key or bearer JWT                |
| **Payor (client)**    | Browser / mobile / embedded UI | Render checkout, access session-scoped payment state, update UI in realtime               | Session credentials (no server keys) |

> Rule of thumb: **the server creates and secures**, the client **renders and observes**.

## Invoice payment flow

This is the default "get paid" flow: you create a canonical object (**Invoice**) and drive checkout from it.

1. **Create an invoice (server)**
   Create the invoice from your backend using your merchant auth.

2. **Present checkout (client)**
   Send the payor to a hosted checkout experience or initialize an embedded flow via a payment session.

3. **Track status (server or client)**
   Choose one (or both):
   * **WebSockets** for realtime updates (best UX and dashboards)
   * **REST polling** for simple "check status" or a fallback path

4. **Reconcile (server)**
   Use the **invoice** and **invoice\_payment** objects for reconciliation with provider-neutral settlement statuses.

> **Invoice status is the source of truth.** UI can be realtime, but business logic should anchor on the invoice lifecycle.

### Sequence diagram (mental model)

```mermaid theme={null}
sequenceDiagram
  participant M as Merchant Server
  participant P as Payor Client
  participant U as User Account
  participant Pepay as Pepay API
  participant B as User Bank Account

  M->>Pepay: Create Invoice
  Pepay-->>M: invoice_id + checkout details
  M-->>P: Render checkout (hosted or embedded)

  P->>Pepay: Initialize Payment Session (session-scoped)
  Pepay-->>P: Session payment data

  P->>Pepay: Pay
  Pepay-->>M: Event: invoice.updated (paid/underpaid/etc)
  M->>Pepay: Fetch invoice + invoice_payment for reconciliation

  Pepay-->>U: Credit stablecoin deposit to user account
  U->>Pepay: Request off-ramp payout
  Pepay-->>B: Send payout to linked bank account
  Pepay-->>U: Return payout status via Pepay API
```

(Keep routes in the API reference pages; this page just explains the shape of the flow.)

## Commerce flow (search -> cart -> checkout -> order)

Commerce flows are for "pay for a thing" use cases: catalog/search, carts, checkout, orders, with invoices powering settlement under the hood.

1. **Search / catalog**
   Find products and offers.

2. **Cart**
   Build a cart (payor-side) or manage carts on the merchant side (ops workflows).

3. **Checkout**
   Estimate totals, collect shipping and address details, and **create an invoice** as the payment anchor.

4. **Orders and payments**
   Track order lifecycle and payment state via REST and/or realtime events.

> Commerce gives you an order lifecycle. **Invoices give you settlement and reconciliation.**

## Realtime delivery model

Pepay websocket streams are designed for **at-least-once delivery**. Your integration should assume an event may be delivered more than once.

Recommended pattern:

* **Deduplicate** by `event.id`
* **Persist a cursor** (last seen event id or timestamp) so you can resume after reconnects
* **Make handlers idempotent** (safe to process the same update twice)

## Environments

Pepay separates **deployment** from **network context**:

* **Base URL** selects the deployment (local, staging, production).
* **Network environment** internally determines access to devnet or mainnet payments.

Mainnet access is gated. Merchants must request activation before using the mainnet payment environment.
If your account is in devnet, invoices run on full testnet environments for each supported chain.

Next: [Security](/overview/security)