Oi, DEV! 👋
Crie sua conta para acessar mais recursos do portal.

🔑 Entrar🆕 Criar conta💓 Saúde dos Serviços
🔙 Voltar para problemas
e-Bank 422beneficiariocodigo invalidoregisterresponseexceptionebank

O código do beneficiário está incorreto ou é inválido

Este erro ocorre durante o registro do boleto quando o banco retorna: O código do beneficiário está incorreto ou é inválido.

Atualizado em 27 de fev. de 2026, 17:59

Problema

Este erro ocorre durante o registro do boleto quando o banco retorna:

O código do beneficiário está incorreto ou é inválido.

Isso significa que o campo beneficiario.codigo enviado no JSON não está no padrão esperado pelo banco.

Exemplo do trecho envolvido:


"beneficiario": {
    "codigo": "xxxxxxx",
    "inscricao": "99999999999999",
    "nome": "Unifake",
    "conta": {
        "banco": "1",
        "agencia": "999",
        "numero": "999"
    },
    "codigoConvenio": "xxxxxxx"
}

Se o valor enviado estiver incorreto, incompleto ou diferente do convênio configurado no banco, a rejeição ocorrerá.

Solução

Como resolver

Você possui duas opções:

✅ Opção 1 — Informar o código correto

Verifique junto ao banco qual é o código do beneficiário correto (normalmente vinculado ao convênio) e envie exatamente o valor esperado no campo:

"beneficiario":{ "codigo": "CODIGO_CORRETO_AQUI"}

O valor deve corresponder ao cadastro do convênio no banco.

✅ Opção 2 — Não enviar o código e deixar o e-Bank montar

Se você estiver utilizando o configurationId, pode simplesmente não enviar o campo beneficiario.codigo.

Nesse cenário, o e-Bank irá montar automaticamente o código correto com base na configuração cadastrada.

Boa prática: Quando estiver usando configurationId, prefira deixar que o e-Bank gerencie os dados bancários sensíveis para evitar inconsistências.

Após ajustar o JSON ou remover o campo, tente novamente o registro do boleto.