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.- Create an invoice (server) Create the invoice from your backend using your merchant auth.
- Present checkout (client) Send the payor to a hosted checkout experience or initialize an embedded flow via a payment session.
-
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
- 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)
(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.- Search / catalog Find products and offers.
- Cart Build a cart (payor-side) or manage carts on the merchant side (ops workflows).
- Checkout Estimate totals, collect shipping and address details, and create an invoice as the payment anchor.
- 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.