Validar um Boleto

Validação de boleto é um recurso utilizado para verificar a veracidade de um Boleto emitido por outra instituição financeira ou fatura. Também é possível verificar o valor atual de uma fatura em atraso, pois taxas e juros deverão ser aplicadas a esta fatura e, o valor atualizado será retornado na requisição, além de visualizar todas as informações do boleto, como beneficiário, valor, vencimento, banco emissor e etc. Para realizar a consulta de um pagamento, o Cliente precisa informar a linha digitável do pagamento que deseja realizar. Nessa funcionalidade será efetuado uma consulta na CIP para validar e trazer as informações do pagamento a ser realizado.

Como validar um boleto

ENDPOINT: https://kaizen.bt-staging.app/boletos-payment/validate/

Esse endpoint utiliza o método GET.

Modelo de requisição:

Para efetuar a consulta de um boleto ou fatura, basta informar a linha digitável no "params" da requisição.

Modelo de resposta:

{
    "paymentInfo": {
        "assignor": "BANCO GERADOR S.A.",
        "traders": {
            "recipient": "BENEFICIARIO AMBIENTE HOMOLOGACAO",
            "recipientDocument": "21.568.259/0001-00",
            "payerDocument": "96.906.497/0001-00",
            "payerName": "PAGADOR AMBIENTE HOMOLOGACAO"
        },
        "expiresAt": "2022-11-04T00:00:00.000Z",
        "totalAmount": 1500,
        "amountDetails": {
            "discount": 0,
            "fineAmount": 0,
            "interestAmount": 0,
            "paymentAmountUpdated": 1500,
            "totalAmount": 1500,
            "minValue": 0,
            "maxValue": 1500,
            "totalWithDiscount": 0,
            "totalWithAdditional": 0
        },
        "transactionId": 816889788,
        "type": "Compensation",
        "initeHour": "07:00",
        "endHour": "20:00",
        "digitableLine": "12190000050000001111442325241141800000000000000",
        "nextBusinessDay": null,
        "paymentDeadline": "2022-12-03T00:00:00.000Z",
        "allowChangeValue": true,
        "nextSettle": "N"
    }
}

curl --location --request GET 'https://kaizen.bt-staging.app/boletos-payment/validate/12198000000000000000000000000011114232524114' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJtRE1HODVUSjc4YXk0amRKbEJreFpDd3pINF9vV3cwV0FxWjF1ODR3MUVjIn0.eyJleHAiOjE2Njc1MzU2NzEsImlhdCI6MTY2NzQ5OTY3MSwianRpIjoiNTA3MWYzYTUtYWY5OC00ZjMyLWJkM2QtYjYxYzQ2NTY5NzY0IiwiaXNzIjoiaHR0cDovL2tleWNsb2FrLmtleWNsb2FrOjgxODAvYXV0aC9yZWFsbXMvZGlnaXRhbC1hY2NvdW50IiwiYXVkIjpbImJhY2tvZmZpY2UtdWkiLCJjbGllbnQtdWkiLCJhY2NvdW50Il0sInN1YiI6ImI2MGY2MThjLTIzNmYtNDI3Mi04YWY0LWU1ZTMzYmRmYjUyZCIsInR5cCI6IkJlYXJlciIsImF6cCI6ImFkbWluIiwiYWNyIjoiMSIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsImFkbWluIiwidW1hX2F1dGhvcml6YXRpb24iLCJkZWZhdWx0LXJvbGVzLWRpZ2l0YWwtYWNjb3VudCJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImJhY2tvZmZpY2UtdWkiOnsicm9sZXMiOlsiYWRtaW4iXX0sImNsaWVudC11aSI6eyJyb2xlcyI6WyJhZG1pbiJdfSwiYWRtaW4iOnsicm9sZXMiOlsidW1hX3Byb3RlY3Rpb24iXX0sImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImNsaWVudElkIjoiYWRtaW4iLCJjbGllbnRIb3N0IjoiMTAuMTk3LjcuMTI2IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsImFkbWluIiwidW1hX2F1dGhvcml6YXRpb24iLCJkZWZhdWx0LXJvbGVzLWRpZ2l0YWwtYWNjb3VudCJdLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtYWRtaW4iLCJjbGllbnRBZGRyZXNzIjoiMTAuMTk3LjcuMTI2In0.NP9zxtFbW6qWKAaPCdtOZOp5bf7sdVyek3nMqK3n05Ccn3kwrLBhUEd63VpGWu_gFmqpvYNYpkEeS01wO5VIVIm5Km4A2WvctdRzZmm1T50kO04fSusjt5jFLzMxvM2wIayqb4IJemtR1AB0mImd-ZG6GQjM8WJYn4xyQoE5RrpCKvFT6jI_358SjnQU1CbmHUodXkbmQpAAnO4Jp1ZsO7Rmm3jnIH9pBPB-r-jFOBihfvNQaNKBWkw6AtiMnPEGXDR-iY2yyrvOLLpWBVIJGOIp-vUp9LKAPBwSKegaWwuuh_I5SM2qT21bYMV6oJQBbNIVzPzxt0BsK5in09HykA'

Descrição dos campos:

Campo	Descrição
paymentInfo.traders.recipient	Banco emissor/Convênio
paymentInfo.traders.recipient	CNPJ do Emissor
paymentInfo.traders.payerDocument	CPF/CNPJ do pagador do boleto/fatura
paymentInfo.traders.payerName	Nome do pagador do boleto/fatura
paymentInfo.expiresAt	Data de expiração do boleto/fatura
paymentInfo.totalAmount	Valor do boleto/fatura
paymentInfo.amountDetails.calculationDate	Data no qual foi pago o boleto/fatura
paymentInfo.amountDetails.discount	Descontos atribuídos
paymentInfo.amountDetails.interesAmount	Taxas atribuídas
paymentInfo.amountDetails.paymentAmountUpdated	Total de (taxas + descontos + multa)
paymentInfo.amountDetails.totalAmount	Valor atualizado ( valor do boleto + total de taxas)
paymentInfo.digitableLine	Linha digitável do boleto/fatura
paymentInfo.paymentDeadline	Data de vencimento do boleto
paymentInfo.allowChangeValue	Indica se a fatura pode ser paga parcialmente

🚧
Algumas particularidades na validação de contas:
1 - Para consultas de fichas de compensação, retornamos o valor atualizado para o pagamento no campo "totalUpdated". Apenas nas consultas onde o "AllowChangeValue" for true, será possível efetivar o pagamento com um valor diferente do retornado no totalUpdated, lembrando que é necessário respeitar o intervalo máximo(maxValue) e mínimo(minValue);
2 - Para contas do tipo 1 (concessionárias/tributos), é necessário considerar sempre o atributo "dueDate", o qual refere-se a data de vencimento extraída na linha digitável do registro;
3 - Para contas do tipo 2 (ficha de compensação), é necessário considerar sempre o atributo "registerData.dueDateRegister", o qual refere-se a data de vencimento recuperada na consulta junto a CIP (Câmara Interbancária de Pagamentos).

Erros de validação

A tabela abaixo lista alguns possíveis erros que podem acontecer no fluxo de validação de contas:

Mensagem de Erro	Código do Erro	Tipo de Transação
TRANSACAO JA REALIZADA	704	Concessionária e ficha de compensação	Retornar que o pagamento já foi realizado.
PAGAMENTO NAO REALIZADO, ESTE RECEBIMENTO NAO PODE SER REALIZADO POR ESTE CANAL	258	Concessionária e ficha de compensação	Informar que esse boleto específico só é aceito em unidades próprias.
MAXIMO DE DIAS DE ATRASO EXCEDIDO	260	Ficha de compensação	Informar que esse boleto contém regras que não permite o pagamento após alguns dias do seu vencimento.
PAGAMENTO JA EFETUADO	704	Concessionária e ficha de compensação	Alertar o usuário que o pagamento já foi realizado.
DOCUMENTO NAO RECEBIVEL NA INSTITUICAO	245	Ficha de compensação	Informar que não é possível realizar esse tipo de pagamento. Esse retorno é apresentado sempre que a Bit Capital não consegue processar um pagamento devido a uma restrição. Exemplo: pagamento só pode ser realizado em um banco específico.
RECEBIMENTO NAO AUTORIZADO. DOCUMENTO VENCIDO	244	Concessionária e ficha de compensação	Informar que o pagamento está vencido e que existe uma regra que restringe o pagamento.
CODIGO BARRAS INVALIDO	243	Concessionária e ficha de compensação	Alertar sobre o preenchimento de um código de barras invalido.
COD-BARRAS INVALIDO	240	Concessionária e ficha de compensação	Alertar sobre o preenchimento de um código de barras invalido.
PAGAMENTO NAO PERMITIDO	184	Concessionária e ficha de compensação	Informar que não é possível realizar esse tipo de pagamento. Esse retorno é apresentado sempre que a Bit Capital não consegue processar um pagamento devido a uma restrição. Exemplo: pagamento só pode ser realizado em um banco especifico.
TRANSACAO NAO ENCONTRADA	24	Concessionária e ficha de compensação	Deve ser retornado para o usuário que o código de barras ou linha digitável é inválido.
CEDENTE NAO AUTORIZADO. PAGAMENTO NAO EFETUADO.	619	Concessionária e ficha de compensação	Mensagem de retorno para convênios que não são aceitos.
FALHA NA COMUNIC JUNTO AO NOSSO PARCEIRO. FAVOR TENTE NOVAMENTE.	658	Concessionária e ficha de compensação	Nesse caso, como não houve sucesso na tentativa do pagamento, o recomendado é pedir ao usuário que tente efetuar o pagamento novamente.
FALHA NA COMUNIC COM A INSTITUICAO. FAVOR TENTE NOVAMENTE.	620	Concessionária e ficha de compensação	Nesse caso, como não houve sucesso na tentativa do pagamento, o recomendado é pedir ao usuário que tente efetuar o pagamento novamente.
DIVERGENCIA NO REGISTRO. NAO FOI POSSIVEL CALCULAR JUROS/MULTAS, ENTRE EM CONTATO COM O FAVORECIDO	648 ou 649	Ficha de compensação	Problema com o registro na CIP, para esse cenário é necessário entrar em contato com o favorecido. E o boleto não poderá ser pago.
BOLETO DE PAGAMENTO JA BAIXADO	704	Ficha de compensação	Essa mensagem é apresentada quando a data limite do pagamento já expirou. Dessa forma, o seu usuário deve ser informado sobre a expiração.
BOLETO ENCONTRADO NA BASE E CLIENTE BENEFICIARIO INAPTO NA INSTITUICAO EMISSORA DO BOLETO	630	Ficha de compensação	Deve ser apresentada uma mensagem informando que o beneficiário está inapto na instituição emissora do boleto, portanto, ele deve entrar em contato com ela.
BOLETO ENCONTRADO NA BASE E CLIENTE BENEFICIARIO SEM CADASTRO	631	Ficha de compensação	Deve ser apresentada uma mensagem informando que o beneficiário está inapto na instituição emissora do boleto, portanto, ele deve entrar em contato com ela.
BOLETO ENCONTRADO NA BASE E CLIENTE BENEFICIARIO EM ANALISE NA INSTITUICAO EMISSORA DO BOLETO	632	Ficha de compensação	Deve ser apresentada uma mensagem informando que o beneficiário está inapto na instituição emissora do boleto, portanto, ele deve entrar em contato com ela.
BOLETO EXCEDEU O LIMITE DE PAGAMENTOS PARCIAIS	633	Ficha de compensação	Retornar para o usuário que ele tem restrições com o beneficiário.

Como validar um boleto

Modelo de requisição:

Modelo de resposta:

Descrição dos campos:

🚧Algumas particularidades na validação de contas:

Erros de validação

🚧
Algumas particularidades na validação de contas: