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

# Capabilities

> A practical overview of Pepay's core building blocks.

## 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 **five core objects** plus **two ways to receive updates**. Everything else composes from there.

For teams reading these docs, that means Pepay is not only about accepting payments and powering commerce. It also gives you a stablecoin deposit and off-ramp primitive for KYC-gated cash-out flows.

## Core primitives

| Primitive                    | What it is                                                                                                     | What you use it for                                                        |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Invoices**                 | The 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.                   |
| **On/Off-Ramps**             | KYC-gated stablecoin deposit and bank payout flows, giving you on-ramp/off-ramp coverage across 30+ countries. | User cash-out, treasury withdrawals, and compliant fiat payout workflows.  |
| **Commerce**                 | Merchant commerce APIs for catalog/search, carts, checkout, orders, and payments.                              | "Pay for a thing" workflows: carts, orders, fulfillment-adjacent commerce. |
| **Events**                   | A 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):

```json theme={null}
{
  "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](/overview/how-it-works)