Ciclo de un cobro

Un cobro PIX creado vía POST /v1/pix pasa por estos estados.

Diagrama

Crédito al saldo

Cuando un cobro se paga, el valor neto (amountCents - feeCents) se acredita al saldo del comerciante. Las tarifas (feeCents) se calculan y congelan en el momento de la creación — cambios posteriores en la tabla de tarifas no afectan a cobros ya creados.

Consistencia eventual del saldo

El saldo (GET /v1/balance) se actualiza en pocos segundos tras la confirmación. Para conciliación fina, usa GET /v1/transactions/:id, que refleja el estado en tiempo real.

Expiración

expiresInDays (1 a 30, por defecto 2) define cuántos días el cobro queda válido. Tras expirar, el estado pasa a expired.

Confirmando el pago

Tienes dos opciones complementarias:

Webhook (recomendado) — recibe payment.paid automáticamente. Ver Webhook.
Polling — consulta GET /v1/transactions/:id periódicamente. Útil como fallback si el webhook falla.

Como el webhook se entrega en una sola tentativa, el polling como fallback es muy recomendado para confirmación crítica de pedidos.

Autenticación Ciclo de un retiro