Skip to main content

​
A practical overview of Pepay’s building blocks

Pepay keeps the integration surface intentionally small: a handful of primitives that stay stable as you move from your first payment flow to fully embedded commerce. Think of Pepay as four core objects plus two ways to receive updates. Everything else composes from there.

​
Core primitives

PrimitiveWhat it isWhat you use it for
InvoicesThe canonical payment object with a clear lifecycle.A single source of truth for settlement and reconciliation.
Payment Sessions (payor)Browser-safe session credentials for checkout flows (x-session-token + x-signature).Secure payer-side flows in web/mobile/embedded contexts.
CommerceMerchant commerce APIs for catalog/search, carts, checkout, orders, and payments.”Pay for a thing” workflows: carts, orders, fulfillment-adjacent commerce.
EventsA consistent event envelope for realtime delivery and historical lookup.Realtime UX, operational visibility, and state changes you can trust.

​
Invoice lifecycle (high level)

Invoices progress through a simple lifecycle: unpaid -> paid | underpaid | expired | canceled When you’re building app logic, anchor on invoice status. It is designed to stay provider- and chain-neutral.

​
Realtime updates: choose your integration style

Pepay supports two straightforward ways to stay in sync:
  • WebSockets: best for low-latency UIs, embedded checkout, and dashboards.
  • REST polling: best for simple “check status” workflows (and as a reliable fallback).
Many teams use both: WebSockets for speed, polling for resilience on critical paths.

​
Example: Event envelope

Pepay events arrive in a consistent envelope across realtime delivery (and historical lookup where applicable): 
{
  "id": "evt_1734780000000-123",
  "object": "event",
  "created": 1734780000,
  "type": "invoice.updated",
  "data": {
    "object": {
      "object": "invoice",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "paid",
      "invoice_type": "standard",
      "environment": "devnet"
    }
  }
}

​
What to rely on

  • type tells you what changed.
  • data.object.object and data.object.id tells you which resource changed.
  • data.object.status is typically the business-relevant state (for example, what your UI, order system, or fulfillment flow should react to).

​
What you can count on

Pepay is designed to feel predictable under real production constraints:
  • Consistent auth patterns across server and browser contexts (sessions where they belong, server auth where it is safer).
  • A typed SDK surface (JS/TS) that maps cleanly to stable API routes.
  • Provider details stay behind the curtain. Merchant-facing objects and statuses do not leak internal routing complexity.
  • Events are a first-class changelog with the same structure whether you’re streaming updates or replaying history.
Next: How Pepay works