Ciclo de uma cobrança

Uma cobrança PIX criada via POST /v1/pix passa por estes estados.

Diagrama

Crédito do saldo

Quando uma cobrança é paga, o valor líquido (amountCents - feeCents) é creditado no saldo do lojista. As taxas (feeCents) são calculadas e congeladas no momento da criação — alterações de tabela de taxas posteriores não afetam cobranças já criadas.

Eventual consistência do saldo

O saldo (GET /v1/balance) é atualizado em até alguns segundos após a confirmação. Para reconciliação fina, use GET /v1/transactions/:id que reflete o status em tempo real.

Expiração

expiresInDays (1 a 30, default 2) define quantos dias a cobrança fica válida. Após expirar, o status passa a expired.

Confirmando o pagamento

Você tem duas opções complementares:

Webhook (recomendado) — receba payment.paid automaticamente. Veja Webhook.
Polling — consulte GET /v1/transactions/:id periodicamente. Útil como fallback se o webhook falhar.

Como o webhook é entregue em uma única tentativa, o polling como fallback é fortemente recomendado para confirmação crítica de pedidos.

Autenticação Ciclo de um saque