Status possíveis
Entenda os status possíveis de um pagamento, quando cada um ocorre e como tratar estados finais, intermediários e comportamentos de Sandbox.
O status indica em qual etapa está um pagamento de conta e qual ação sua integração deve executar. Use essa informação para manter a operação pendente, concluir o pagamento, tratar uma falha, cancelar o fluxo ou registrar um estorno.
Status e tratamento recomendado
| Status | O que representa | Como tratar na integração |
|---|---|---|
PENDING | Aguardando processamento. | Mantenha a operação pendente e aguarde uma atualização. |
BANK_PROCESSING | Enviado para o banco. | Mantenha a operação em processamento. Não considere o pagamento concluído. |
PAID | Pagamento realizado. | Marque a operação como concluída. |
FAILED | O pagamento falhou. | Consulte o motivo da falha antes de orientar uma nova tentativa. |
CANCELLED | O pagamento foi cancelado. | Interrompa o fluxo e registre o cancelamento. |
REFUNDED | O pagamento foi estornado. | Atualize a operação para refletir o estorno. |
AWAITING_CHECKOUT_RISK_ANALYSIS_REQUEST | Pagamento em análise. | Mantenha a operação pendente e aguarde uma nova atualização antes de concluir o fluxo. |
Como os status podem evoluir
Os fluxos abaixo representam transições comuns. Não assuma que todo pagamento passará obrigatoriamente por todos os estados intermediários.
Pagamento concluído
%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
A["PENDING"] --> B["BANK_PROCESSING"]
B --> C["PAID"]
classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
class A inicio
class B validacao
class C sucesso
linkStyle default stroke:#94A3B8,stroke-width:2px
Falha no processamento
%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
A["PENDING"] --> B["FAILED"]
classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
class A inicio
class B respostaNao
linkStyle default stroke:#94A3B8,stroke-width:2px
Ao receber FAILED, consulte o motivo retornado antes de realizar uma nova tentativa.
Pagamento cancelado
%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
A["PENDING"] --> B["CANCELLED"]
classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
class A inicio
class B sucesso
linkStyle default stroke:#94A3B8,stroke-width:2px
Pagamento estornado
%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
A["PAID"] --> B["REFUNDED"]
classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
class A inicio
class B sucesso
linkStyle default stroke:#94A3B8,stroke-width:2px
Pagamento em análise
%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
A["AWAITING_CHECKOUT_<br/>RISK_ANALYSIS_REQUEST"] --> B["Aguardar nova atualização"]
classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px
class A inicio
class B sucesso
linkStyle default stroke:#94A3B8,stroke-width:2px
Acompanhe as mudanças por Webhook
Para acompanhar o processamento, prefira os Eventos para Pague Contas em vez de realizar consultas periódicas à API.
Nos eventos recebidos, event identifica a alteração notificada e bill.status representa o estado atual do pagamento. Utilize bill.id para relacionar a atualização à operação armazenada no seu sistema.
Quando receber BILL_FAILED, consulte bill.failReasons antes de decidir se uma nova tentativa é necessária.
Tratamento na integração
Considere PENDING, BANK_PROCESSING e AWAITING_CHECKOUT_RISK_ANALYSIS_REQUEST como estados não conclusivos. Não libere um fluxo dependente do pagamento enquanto a operação permanecer nesses estados.
PAID, FAILED, CANCELLED e REFUNDED representam resultados que exigem uma atualização do estado da operação no seu sistema.
Ao processar atualizações recebidas por Webhook, trate os eventos de forma idempotente para evitar efeitos duplicados.
Em Sandbox, nenhum pagamento é realmente compensado. Para testar o Pague Contas, utilize um boleto gerado na própria conta Sandbox. Boletos reais de bancos externos podem retornar erro ou status
FAILED.
Próximos passos
Updated 13 days ago