Charge lifecycle

A PIX charge created via POST /v1/pix goes through these states.

Diagram

Balance credit

When a charge is paid, the net amount (amountCents - feeCents) is credited to the merchant’s balance. Fees (feeCents) are calculated and frozen at creation time — subsequent fee-table changes do not affect already-created charges.

Eventual balance consistency

The balance (GET /v1/balance) updates within a few seconds after confirmation. For fine-grained reconciliation, use GET /v1/transactions/:id, which reflects the status in real time.

Expiration

expiresInDays (1 to 30, default 2) defines how many days the charge stays valid. After expiration, the status becomes expired.

Confirming the payment

You have two complementary options:

Webhook (recommended) — receive payment.paid automatically. See Webhook.
Polling — query GET /v1/transactions/:id periodically. Useful as a fallback if the webhook fails.

Since the webhook is delivered in a single attempt, polling as a fallback is strongly recommended for critical order confirmation.

Authentication Withdrawal lifecycle