Pix
Estados da cobrança
Cada estado de uma cobrança Pix, as transições possíveis e o evento enviado em cada uma.
O campo status da cobrança mostra em que ponto ela está. Um estado final nunca volta atrás: uma cobrança paga nunca volta a pending.
Estados
| Estado | Significado | O que fazer |
|---|---|---|
created | Pedido registrado; a emissão do Pix está em andamento ou com resultado ainda desconhecido. | Consulte de novo em alguns segundos. Não crie outra cobrança. |
pending | QR emitido, aguardando pagamento. | Mostre o QR e aguarde o webhook. |
paid | Pagamento confirmado. | Confirme pela consulta e libere o pedido. |
partially_refunded | Parte do valor foi devolvida ao pagador. | Veja refunded_cents. |
refunded | Todo o valor foi devolvido. | — |
expired | A validade do QR acabou sem pagamento. | Ofereça uma nova cobrança. |
cancelled | Cobrança cancelada antes do pagamento. | Ofereça uma nova cobrança. |
failed | A emissão foi recusada ou não pôde ser feita. | Mostre failure_message (texto fixo, veja abaixo); tente de novo com outro order_reference. |
Transições
| De | Para | Evento |
|---|---|---|
created | pending | charge.pending |
created | failed | charge.failed |
created | paid | charge.paid |
created | cancelled | charge.expired com data.status: "cancelled" |
pending | paid | charge.paid |
pending | expired | charge.expired |
pending | cancelled | charge.expired com data.status: "cancelled" |
expired ou cancelled | paid | charge.paid com late_payment: true (pagamento tardio) |
paid | partially_refunded ou refunded | charge.refunded |
partially_refunded | refunded | charge.refunded |
failed e refunded são finais.
Não existe um evento próprio para o cancelamento: uma cobrança cancelada antes do pagamento chega como charge.expired, com data.status igual a cancelled. Trate os dois casos do mesmo jeito (o QR não vale mais) e use data.status se precisar diferenciar.
Motivos da recusa
Quando status é failed, failure_message traz um destes textos fixos, próprios para exibir. Para decidir no código, use reason do evento charge.failed (veja Eventos).
failure_message | Quando |
|---|---|
| Emissão recusada pela análise de risco. | A análise de risco recusou a cobrança. |
| Emissão recusada: dados da cobrança ou do pagador inválidos ou incompletos. Confira nome, CPF/CNPJ, e-mail e telefone do pagador. | Faltou dado do pagador ou algum valor foi recusado. Corrija e crie outra cobrança. |
| Emissão recusada pela análise de conformidade. | A análise de conformidade recusou a cobrança. |
| Emissão recusada: limite de recebimento da conta atingido. | O limite de recebimento da sua conta foi atingido. |
| Emissão recusada: o segmento desta venda não é aceito para a conta. | O segmento da venda não é aceito no seu contrato. |
| Emissão recusada por pendência no cadastro da conta. Fale com a Koku. | Há pendência no cadastro da sua conta. |
| Emissão recusada: recebimentos bloqueados para a conta. Fale com a Koku. | Recebimentos bloqueados. |
| Emissão recusada: recebimentos suspensos para a conta. Fale com a Koku. | Recebimentos suspensos. |
| Emissão recusada pela rede de processamento. | Outra recusa definitiva. |
| Processamento Pix indisponível no momento da emissão; nenhum QR Code foi gerado. Crie uma nova cobrança com outro order_reference. | Falha técnica na emissão. |
| A emissão do Pix não foi concluída; nenhum QR Code foi gerado. Crie uma nova cobrança com outro order_reference. | A emissão não chegou a ser confirmada. |
Nos estados diferentes de failed, failure_message vem null.
Pagamento tardio
Se o comprador pagar depois da expiração (por exemplo, com o QR já salvo no aplicativo do banco), o dinheiro entrou de verdade: a cobrança vira paid com late_payment: true e a Koku abre um caso de revisão (case_id no evento charge.paid). A Koku analisa o caso e combina com você se o valor fica como venda ou volta ao comprador; o desfecho chega em case.resolved. Enquanto isso, não entregue o pedido sem falar com a Koku (veja Suporte).
Pagamento duplicado
Se o mesmo QR for pago duas vezes, a cobrança continua paid (uma venda) e o segundo pagamento fica retido para devolução ao pagador. A Koku envia charge.duplicate_payment e o valor aparece como bloqueado no saldo até a devolução. payments_count mostra quantos pagamentos a cobrança recebeu.
charge.duplicate_payment{
"id": "evt_6e2a8c4d0f5b4e9a1c3d5f7b9e1a4c60",
"type": "charge.duplicate_payment",
"version": "v1",
"created_at": "2026-10-07T15:35:20.000Z",
"environment": "production",
"data": {
"charge_id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
"order_reference": "PEDIDO-1001",
"payment_id": "f2c8a5e1-3b7d-4e90-a6c4-8d1f5b2e9a73",
"classification": "duplicate",
"amount_cents": "15990",
"end_to_end_id": "E12345678202610071535f6G7h8J9k0L",
"case_id": "6a2f9d14-8e3b-4c57-b1d0-5e9a7c3f2b81"
}
}