Payments & states

The database is authoritative for session state. UI events do not confirm received money.

Available flow

1. Your backend creates a checkout session.
2. The payer reviews amount, network, and personal details.
3. The browser creates a sandbox operation with an idempotency key.
4. The API returns sandbox_pending and an explicitly non-payable code.
5. Simulation finishes as sandbox_completed and persists an event.

Each session has at most one payment. Changing an idempotency key cannot create a second payment.

Queries

GET /v1/payments requires payments:read. It returns up to 100 workspace payments, without documents, emails, or raw provider data.

GET /v1/metrics requires metrics:read. Financial totals count only live payments in completed state. Sandbox activity is counted separately and never contributes to settled volume.

Reserved live states

created, processing, paid, completed, expired, and failed belong to the operational plan. paid (Pix received) and completed (crypto settled) are not equivalent. The live state machine and reconciliation need provider validation before exposure.

Amounts

BRL is stored as integer cents. Digital assets will require integer units with asset-specific precision. Never maintain a financial balance from floating-point values or a UI quote.