Status da transação
Decida o que fazer com cada cobrança pelo número em creditCardPayment.status; os códigos de retorno servem para registrar e explicar o resultado. Na cobrança Pix, o status fica em pixPayment.status; veja Status do Pix.
Status da cobrança
status | Nome | Descrição |
|---|---|---|
0 | NotFinished | Pagamento não concluído por falha no processamento. |
1 | Authorized | Pagamento autorizado, ainda sem captura. |
2 | PaymentConfirmed | Pagamento confirmado. |
3 | Denied | Pagamento recusado pelo emissor. |
10 | Voided | Pagamento cancelado. |
11 | Refunded | Pagamento estornado. |
12 | Pending | Aguardando o retorno da instituição financeira. |
13 | Aborted | Pagamento cancelado por falha no processamento. |
status | O que fazer |
|---|---|
2 | Libere o pedido. É o único status que aceita estorno. |
3 | Mostre ao cliente o returnMessage da resposta da criação e veja se vale tentar de novo com o mesmo cartão. |
0 ou 13 | Trate a cobrança como não paga e crie outra se o cliente quiser tentar de novo. |
12 ou 1 | Aguarde o aviso charge.update com o status final. |
Numa cobrança avulsa a autorização e a captura acontecem na mesma chamada, então o primeiro status que você vê costuma ser 2, 3, 12, 0 ou 13. Os status 1 e 10 podem aparecer conforme o provedor de pagamento da conta.
Ciclo de vida
Depois de um PUT /charges/{chargeId}/reverse, a cobrança continua em 2 com reversedAmount preenchido até a confirmação do cancelamento, que leva o status a 10 ou 11.
Se vale tentar de novo
No pagamento negado (3), creditCardPayment.retryAllowed e creditCardPayment.retryAfter dizem se o emissor aceita outra tentativa com o mesmo cartão.
- Onde vêm: na criação e na consulta por id (GET /charges/{chargeId}). São
nullquando o pagamento não foi negado. - Onde não vêm: na listagem, no estorno, nas respostas a chargeback e nos avisos.
retryAllowed | retryAfter | O que significa | O que fazer |
|---|---|---|---|
false | null | Recusa definitiva. | Peça outro cartão. A nova tentativa com o mesmo cartão responde 422 com PZ202 por 30 dias, sem criar cobrança. |
true | "2026-11-09T18:40:12.000Z" | O emissor deu um prazo. | Tente depois de retryAfter ou peça outro cartão. Antes do prazo, a tentativa responde 422 com PZ203. |
true | null | Recusa comum. | Pode tentar de novo, dentro dos limites da bandeira. |
Os códigos de cada bandeira estão em Programa de retentativa das bandeiras.
Onde o status aparece
- Na resposta de POST /charges, com o resultado da autorização.
- Em GET /charges/{chargeId} e em cada item de GET /charges, com o estado atual.
- Em
data.creditCardPayment.statusde cada aviso. - Na resposta de PUT /charges/{chargeId}/reverse; veja Ciclo de vida.