ITP - Possíveis Erros de Pagamento
Visão Geral
Esta página lista os erros que podem ocorrer durante a execução e liquidação de pagamentos Pix via ITP, com descrição das causas, se são retriáveis, e orientações de tratamento.
Erros no Consentimento (Criação — POST /payment-initiation)
POST /payment-initiation)| Código | Título | Causa | Retriável? |
|---|---|---|---|
DATA_PAGAMENTO_INVALIDA | Data de pagamento inválida | A date está no passado ou fora do intervalo permitido | ✅ Corrija a data e tente novamente |
BRAND_NAO_ENCONTRADA | Marca não encontrada | brandId inexistente ou com status INACTIVE | ❌ Selecione outra instituição |
CPF_CNPJ_INVALIDO | CPF/CNPJ inválido | Documento do creditor com dígitos verificadores errados | ❌ Corrija o documento |
PROXY_INVALIDO | Chave Pix inválida | proxy com formato incompatível com o localInstrument | ❌ Corrija a chave Pix |
VALOR_INVALIDO | Valor inválido | amount com formato incorreto (mais de 2 casas decimais, vazio, etc.) | ❌ Corrija o valor |
TIPO_PAGAMENTO_INVALIDO | Tipo de pagamento inválido | Campo type diferente de PIX | ❌ Use type: PIX |
Erros no Callback (POST /payment-initiation/callback)
POST /payment-initiation/callback)| Cenário | Causa | Como Tratar |
|---|---|---|
invalid_request_uri | code expirado. O callback não foi chamado a tempo | Redirecione o usuário para iniciar um novo consentimento |
access_denied | Usuário rejeitou o consentimento | Exiba mensagem ao usuário e ofereça a opção de tentar novamente |
state não encontrado | state não corresponde a nenhuma payment initiation ativa | Verifique o armazenamento do state no fluxo |
code já utilizado | Tentativa de trocar o mesmo code duas vezes | Cada code é de uso único — trate idempotência no callback |
Erros na Liquidação — Rejeições RJCT
RJCTQuando um pagamento é rejeitado pelo SPB ou pela detentora, o campo rejectionReason no webhook indica o motivo:
| Código | Descrição | Retriável? | Orientação |
|---|---|---|---|
SALDO_INSUFICIENTE | Saldo insuficiente na conta do pagador | ✅ Intradia | Notifique o usuário para repor saldo e tente novamente |
VALOR_INVALIDO | Valor fora do permitido pela detentora | ❌ | Verifique limites da conta do usuário |
CONTA_NAO_PERMITE_PAGAMENTO | Conta devedora não habilitada para pagamentos Pix | ❌ | Oriente o usuário a habilitar Pix na detentora |
PAGAMENTO_DIVERGENTE_CONSENTIMENTO | Dados do pagamento divergem do consentimento aprovado | ❌ | Crie novo consentimento com os dados corretos |
CONSENTIMENTO_INVALIDO | Consentimento não está em status AUTHORISED | ❌ | Crie novo consentimento |
NAO_INFORMADO | Motivo não informado pela detentora | ✅ Extradia | Aguarde e tente criar novo consentimento |
FALHA_INFRAESTRUTURA | Falha interna na detentora ou SPB | ✅ Após intervalo | Aguarde 30s–1min e tente novamente |
LIMITE_PERIODO_VALOR_EXCEDIDO | Limite de valor diário/semanal/mensal atingido | ❌ | Aguarde reset do período ou oriente o usuário |
LIMITE_PERIODO_QUANTIDADE_EXCEDIDO | Limite de quantidade de transações do período atingido | ❌ | Aguarde reset do período |
CONTA_DESTINO_INVALIDA | Conta ou chave Pix do recebedor inválida | ❌ | Verifique os dados do creditor e creditorAccount |
CAMPO_INVALIDO | Campo obrigatório ausente ou com valor inválido | ❌ | Revise os dados enviados no pagamento |
QRCODE_INVALIDO | QR Code expirado ou inválido | ❌ | Solicite novo QR Code ao recebedor |
Janelas de Retry
O Open Finance Brasil define janelas de retry para pagamentos retriáveis:
| Janela | Descrição |
|---|---|
| Intradia | Mesmo dia. Tente novamente até o fim do horário de funcionamento do SPI (tipicamente 20h) |
| Extradia | Até 7 dias corridos a partir da data original do pagamento |
Pagamentos com rejeição definitiva (não retriáveis) não devem ser retentados. Crie um novo consentimento após corrigir a causa raiz.
Diagrama de Decisão de Retry
flowchart TD
A["Pagamento RJCT\nrecebido via webhook"] --> B{rejectionReason\nretriável?}
B -->|Sim\n(SALDO_INSUFICIENTE,\nFALHA_INFRAESTRUTURA,\nNAO_INFORMADO)| C{Dentro da\njanela de retry?}
B -->|Não| D["❌ Encerrar tentativas\nNotificar usuário\nCriar novo consentimento\nse aplicável"]
C -->|Intradia| E["⏳ Aguardar intervalo\n(30s–5min)\nCriar novo consentimento\ne tentar novamente"]
C -->|Extradia| F["📅 Agendar retry\nem próximo dia útil"]
C -->|Fora da janela| D
style D fill:#f5c6c6,stroke:#c0392b,color:#333
style E fill:#fef9c3,stroke:#f39c12,color:#333
style F fill:#c6e2f5,stroke:#2980b9,color:#333
Pontos de Atenção
Nunca retente com o mesmo consentimento: Como cada consentimento é de uso único, sempre crie uma nova payment initiation para retentar um pagamento. Retentar com consentimentoCONSUMEDretorna422.
ConsentimentoCONSUMED≠ pagamento bem-sucedido: O consentimento vai paraCONSUMEDapós oPOST /pix, mesmo que o pagamento seja posteriormente rejeitado (RJCT). Monitore o status do pagamento via webhook.
Evite comunicarRJCTde infraestrutura ao usuário final: Erros comoFALHA_INFRAESTRUTURAsão transitórios. Mostre ao usuário uma mensagem genérica ("Pagamento temporariamente indisponível, tentando novamente...") enquanto executa o retry em background.
Log detalhado: Registre sempre orejectionReason,endToEndIdepaymentIdem caso de rejeição para facilitar análise e suporte.
Updated about 2 hours ago