Ciclo de vida do pagamento
Os estados de uma cobrança Pix e como ela transita entre eles.
Toda cobrança Pix tem um status que reflete seu estado atual. Em endpoints de pagamentos, esse valor é retornado em Verificar pagamento. O status também aparece nos eventos de webhook.
Estados
| Status | Significado |
|---|---|
ACTIVE | Cobrança criada e aguardando pagamento. |
DONE | Pagamento confirmado e recebido. |
EXPIRED | A cobrança passou da data de expiração sem ser paga. |
CANCELLED | A cobrança foi cancelada antes de ser paga. |
Pagamentos recém-criados sempre começam com status ACTIVE.
Transições
Uma cobrança sempre nasce como ACTIVE e segue para um estado final:
┌──────────────► DONE (pagamento confirmado)
ACTIVE ──────────┼──────────────► EXPIRED (passou da expiração)
└──────────────► CANCELLED (cancelada via API)ACTIVE → DONE: quando o pagador conclui o Pix.ACTIVE → EXPIRED: automaticamente, ao ultrapassar o campoexpiresda cobrança.ACTIVE → CANCELLED: ao chamar Cancelar pagamento.
Os estados DONE, EXPIRED e CANCELLED são finais. Só é possível cancelar uma cobrança enquanto ela estiver ACTIVE.
Acompanhando o status
- Webhooks — o evento
PAYMENTé disparado a cada mudança de status. Recomendado para confirmação automática. Veja Eventos de webhook. - Verificação sob demanda — consulte o status atual com Verificar pagamento.
O campo paid é retornado apenas quando o pagamento foi concluído. A expiração padrão acontece em até 2 horas após a criação do Pix; para ajustar esse prazo, entre em contato com a Paggpix.