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.

Use os status de pagamento para decidir quando aguardar processamento, finalizar uma operação, investigar uma falha ou atualizar o estado interno da sua integração.

Quando usar

Consulte esta página ao tratar o retorno de um pagamento, ao conciliar o estado exibido para o cliente ou ao processar eventos relacionados ao ciclo de pagamento. O status indica se a operação ainda está em processamento, se terminou com sucesso, se falhou ou se foi cancelada/estornada.

Status e tratamento recomendado

Status	Descrição	Como tratar na integração
PENDING	Aguardando processamento.	Mantenha o pagamento como pendente e aguarde uma atualização de status.
BANK_PROCESSING	Enviado para o banco.	Informe que o pagamento está em processamento bancário e não finalize a operação como paga.
PAID	Pago e compensado.	Marque o pagamento como concluído e libere o fluxo dependente da confirmação.
FAILED	Falhou — verifique o motivo no retorno.	Registre a falha, leia o motivo retornado e oriente o usuário a tentar novamente quando aplicável.
CANCELLED	Pagamento cancelado antes da execução.	Interrompa o fluxo de execução e mantenha o histórico do cancelamento.
REFUNDED	Valor estornado.	Atualize o pagamento como estornado e reflita o estorno no saldo ou relatório interno.
AWAITING_CHECKOUT_RISK_ANALYSIS_REQUEST	Em análise.	Trate como estado intermediário: aguarde a conclusão da análise antes de confirmar ou rejeitar o pagamento.

Fluxo comum de status

Após a criação do pagamento, trate PENDING como um estado inicial de espera.
Quando o pagamento for enviado para processamento externo, trate BANK_PROCESSING como um estado intermediário.
Finalize o fluxo somente ao receber um status conclusivo, como PAID, FAILED, CANCELLED ou REFUNDED.
Se receber AWAITING_CHECKOUT_RISK_ANALYSIS_REQUEST, aguarde a análise antes de liberar o produto, serviço ou próxima etapa da jornada.

PENDING → BANK_PROCESSING → PAID
                         ↘ FAILED
PENDING → CANCELLED
PAID → REFUNDED
AWAITING_CHECKOUT_RISK_ANALYSIS_REQUEST → aguardar nova atualização

Campos e decisões importantes

Ao processar a resposta, valide pelo menos estas informações:

Informação	Quando observar	Decisão recomendada
Status do pagamento	Em todas as atualizações	Use o status como fonte principal para atualizar sua base interna.
Motivo da falha	Quando o status for `FAILED`	Exiba uma mensagem operacional adequada e registre o motivo para suporte.
Ambiente	Durante testes em Sandbox	Não use o resultado do Sandbox como evidência de compensação bancária real.

Boas práticas

Não libere acesso, produto ou serviço enquanto o status estiver PENDING, BANK_PROCESSING ou AWAITING_CHECKOUT_RISK_ANALYSIS_REQUEST.
Atualize sua base de forma idempotente (a mesma atualização pode ser recebida mais de uma vez e não deve duplicar efeitos).
Registre o status anterior e o novo status para facilitar auditoria e suporte.
Para falhas, consulte o motivo retornado antes de orientar uma nova tentativa.

📘
Em Sandbox, todos os pagamentos retornam FAILED após a criação. Isso é esperado, pois não há compensação bancária real no ambiente de testes.

Conteúdos relacionados

Introdução - Pague contas: entenda o fluxo geral do produto antes de tratar os status.
Regras importantes: revise regras de negócio que impactam o processamento.
Pagamento imediato x Pagamento agendado: compare os fluxos por tipo de pagamento.
Eventos para pague contas: acompanhe atualizações por Webhook quando sua integração usar eventos.
Testando no Sandbox: valide o comportamento esperado no ambiente de testes.