Status da cobrança

O que cada estado significa e o que você faz em cada um. Esta tabela sai do mesmo código que a API executa — se um estado aparecer aqui, ele existe.

Status	Final?	Significa	O que fazer
`created`	não	Cobrança registrada, QR ainda sendo emitido pelo provedor.	Estado transitório. Consulte de novo em alguns segundos.
`awaiting_payment`	não	QR Code válido, aguardando o pagamento do Pix.	Mostre o QR Code ou o copia-e-cola ao seu cliente.
`paid_pending_settlement`	não	O Pix foi pago, mas o DePix ainda não foi liquidado — há retenção antifraude.	NÃO libere o produto ainda. Use settlement.estimatedAt para informar o prazo ao seu cliente.
`settled`	sim	DePix enviado e confirmado na Liquid. O dinheiro é seu.	Libere o produto. blockchainTxId é o comprovante on-chain.
`expired`	sim	O QR Code venceu sem ser pago.	Crie outra cobrança se o cliente ainda quiser pagar.
`canceled`	sim	Você cancelou a cobrança antes do pagamento.	Nada a fazer.
`failed`	sim	A cobrança não chegou a ser criada no provedor, ou morreu nele.	Crie outra cobrança. O mesmo externalId pode ser reaproveitado.
`refunded`	sim	O Pix foi pago e devolvido. O DePix desta cobrança não sai.	Estorne o pedido no seu sistema.

Como os estados andam

                    ┌──────────────► expired
                    │
created ──► awaiting_payment ──► paid_pending_settlement ──► settled
                    │                       │
                    ├──────────► canceled   └──────────► refunded
                    │
                    └──────────► failed

As transições são unidirecionais: uma cobrança nunca volta a um estado anterior, e um estado final nunca muda. Um evento repetido ou fora de ordem não move nada — é seguro processá-lo duas vezes.

A única exceção: uma cobrança canceled que o cliente pagar assim mesmo volta para paid_pending_settlement. Nosso provedor de Pix não consegue invalidar um QR Code já emitido, e dinheiro que entrou vale mais que o cancelamento que registramos. Tire o QR da frente do cliente ao cancelar.

O atraso entre pago e liquidado

Toda cobrança tem retenção antifraude de 24h entre o Pix cair e o DePix ser liquidado. Nesse intervalo a cobrança fica em paid_pending_settlement, e settlement.estimatedAt diz quando o DePix deve sair.

Libere produto em settled. Em paid_pending_settlement o dinheiro do seu cliente saiu do banco dele, mas ainda não chegou na sua carteira.