¶ Códigos de Erro
Quando um pagamento PIX falha, o webhook MOVEMENT_FAILED retorna informações sobre o erro através dos campos providerRejectedReason e providerErrorCode. Abaixo estão todos os possíveis códigos de erro que podem ser retornados, com suas descrições detalhadas e informações sobre qual participante gera cada erro.
Códigos de Erro
¶ Tabela Completa de Códigos de Erro
| Código | Nome do Erro | Descrição Detalhada | Participante que Gera o Erro |
|---|---|---|---|
| AB03 | Liquidação Abortada por Timeout | Liquidação da transação interrompida devido a timeout no SPI | SPI |
| AB09 | Erro no Agente Credor | Transação interrompida devido a erro no participante do usuário recebedor | Banco recebedor |
| AB11 | Timeout do Agente Devedor | Timeout do participante emissor da ordem de pagamento | SPI |
| AC03 | Número da Conta do Credor Inválido | Agência e/ou conta do recebedor inexistente ou inválida | Banco recebedor |
| AC06 | Conta Bloqueada | Conta do usuário recebedor encontra-se bloqueada | Banco recebedor |
| AC07 | Conta do Credor Encerrada | Conta do recebedor encerrada | Banco recebedor |
| AC14 | Tipo de Conta do Credor Inválido | Tipo incorreto para a conta do recebedor | Banco recebedor |
| AG03 | Transação Não Suportada | Tipo de transação não suportada/autorizada na conta do recebedor (ex: conta salário) | Banco recebedor |
| AG12 | Transferência Interna Não Permitida | Não é permitida ordem de pagamento/devolução dentro do mesmo banco ou entre participantes com o mesmo liquidante | SPI |
| AG13 | Devolução de Retorno Proibida | Não é permitido devolver a devolução de um pagamento instantâneo | SPI |
| AGNT | Agente Incorreto | Participante direto não é liquidante do participante do usuário pagador | SPI |
| AM01 | Valor Zero | Ordem de pagamento com valor zero | SPI |
| AM02 | Valor Não Permitido | Valor ultrapassa o limite permitido para o tipo de conta creditada | Banco recebedor |
| AM04 | Fundos Insuficientes | Saldo insuficiente na conta PI do pagador | SPI |
| AM09 | Valor Incorreto | Devolução com valor que supera o valor original | Banco recebedor |
| AM12 | Valor Inválido | Divergência entre somatória dos valores e campo “valor” | SPI |
| AM18 | Número de Transações Inválido | Quantidade de transações inválida | SPI |
| BE01 | Inconsistência com Cliente Final | CPF/CNPJ do recebedor não consistente com titular da conta | Banco recebedor |
| BE05 | Parte Iniciadora Não Reconhecida | CNPJ do iniciador não cadastrado no arranjo Pix | SPI |
| BE15 | Código de Identificação Inválido | Preenchimento incorreto do campo idConciliacaoRecebedor | Banco recebedor |
| BE17 | Código de Identificação do Credor Inválido | QR Code rejeitado pelo recebedor | Banco recebedor |
| CH11 | Identificador do Credor Incorreto | CPF/CNPJ do recebedor incorreto | Banco recebedor |
| CH16 | Conteúdo Formalmente Incorreto | Conteúdo da mensagem incompatível com as regras de negócio | SPI |
| CN01 | Autorização Cancelada | Agendamento recorrente cancelado com status “ACCR (confirmado)” | Banco recebedor |
| DS04 | Ordem Rejeitada | Ordem rejeitada pelo recebedor | Banco recebedor |
| DS0G | Pagamento Não Permitido | Participante que assinou a mensagem não é autorizado a operar na conta PI debitada | SPI |
| DS27 | Usuário Ainda Não Ativado | Participante não cadastrado ou ainda não iniciou operação no SPI | SPI |
| DT02 | Data de Criação Inválida | Data/hora de envio inválida | SPI |
| DT05 | Data de Corte Inválida | Transação fora do prazo máximo de devolução regulamentado | SPI |
| DUPL | Pagamento Duplicado | Pagamento duplicado com idConciliacaoDoRecebedor igual para o mesmo recebedor | Banco recebedor |
| ED05 | Falha na Liquidação | Erro genérico na liquidação do Pix | SPI / Banco recebedor |
| FF07 | Finalidade Inválida | Inconsistência entre finalidade e blocos Structured | SPI |
| FF08 | EndToEndId Inválido | Identificador mal formatado | SPI |
| FRAD | Origem Fraudulenta | Ordem rejeitada por suspeita de fraude | Banco recebedor |
| MD01 | Sem Mandato | ISPB do facilitador do Pix Saque/Pix Troco inexistente | SPI |
| RC09 | Identificador do Membro Devedor Inválido | ISPB do participante pagador inválido ou inexistente | SPI |
| RC10 | Identificador do Membro Credor Inválido | ISPB do participante recebedor inválido ou inexistente | SPI |
| RR04 | Motivo Regulatório | Pagador sancionado pelo Conselho de Segurança da ONU | Banco recebedor |
| SL02 | Serviço Específico do Agente Credor | Transação referenciada não relacionada a Pix Saque/Troco | Banco recebedor |
| UPAY | Pagamento Indevido | Ausência de recorrência válida/ativa | Banco recebedor |
Categorias
¶ Categorias de Erro
¶ Erros de Liquidação (AB)
AB03: Timeout durante a liquidação
AB09: Erro no participante recebedor
AB11: Timeout no participante pagador
¶ Erros de Conta (AC)
AC03: Conta inexistente ou inválida
AC06: Conta bloqueada
AC07: Conta encerrada
AC14: Tipo de conta inválido
¶ Erros de Autorização (AG)
AG03: Transação não suportada/autorizada
AG12: Transferência não permitida (booktransfer)
AG13: Devolução de devolução não permitida
AGNT: Agente incorreto no fluxo
¶ Erros de Valor (AM)
AM01: Valor zero
AM02: Valor acima do limite
AM04: Saldo insuficiente
AM09: Valor incorreto
AM12: Valor inválido
AM18: Número de transações inválido
¶ Erros de Identificação (BE/CH)
BE01: CPF/CNPJ inconsistente
BE05: Iniciador não reconhecido
BE15: Código de identificação inválido
BE17: QR Code rejeitado
CH11: CPF/CNPJ incorreto
CH16: Conteúdo incorreto
¶ Erros de Processamento (CN/DS/DT)
CN01: Autorização cancelada
DS04: Ordem rejeitada
DS0G: Operação não autorizada
DS27: Usuário não ativado
DT02: Data de criação inválida
DT05: Prazo expirado
¶ Erros Específicos
DUPL: Pagamento duplicado
ED05: Falha na liquidação (genérico)
FF07: Finalidade inválida
FF08: EndToEndId inválido
FRAD: Suspeita de fraude
MD01: Mandato inexistente
RC09/RC10: ISPB inválido
RR04: Motivo regulatório
SL02: Serviço específico
UPAY: Pagamento indevido
Exemplo
¶ Exemplo de Webhook com Código de Erro Detalhado
:"codigo";s:4:"DS27"; Conforme lista de erros: Usuário não ativado.
¶ Participantes que Geram Erros
- Sistema de Pagamentos Instantâneos (SPI): Sistema central do Banco Central
- Banco recebedor: Instituição financeira que recebe o pagamento
- Participante do usuário pagador: Instituição financeira que envia o pagamento
¶ Campos de Retorno
-
providerErrorCode: Contém apenas o código (ex:
"BE17") -
providerRejectedReason: Contém o código e a descrição detalhada (ex:
"BE17 - QR Code rejeitado pelo banco recebedor")
¶ Orientações finais
Os códigos de erro ajudam a identificar o motivo da falha em um pagamento Pix e facilitam a análise da situação informada no retorno do webhook.
Ao verificar uma falha, consulte os campos providerErrorCode e providerRejectedReason para identificar o código retornado, a descrição do erro e o participante responsável pela rejeição.
[INFO] O campo providerErrorCode apresenta apenas o código do erro, enquanto o campo providerRejectedReason pode trazer o código acompanhado da descrição detalhada.
[ALERTA] A identificação correta do código de erro é importante para orientar a tratativa adequada, pois a falha pode ter origem no SPI, no banco recebedor ou na instituição do pagador.
Para mais informações ou auxílio na análise de erros, entre em contato com o suporte oficial da modobank pelo telefone 0800 090 0505.