Validação do título

A validação do título ocorre por meio da linha digitável e é a primeira etapa do processo de pagamento de conta, pois ela verifica se o título está apto a ser pago.

Neste momento, verificamos se o título:

Já foi pago anteriormente;
É recebível na instituição;
Está dentro da data mínima para adiantamento;
Possibilita pagamento parcial;
Não atingiu o limite de pagamentos parciais;
Exige pagamento mínimo ou máximo;
Está dentro da data limite de pagamento;
Pode ser pago após a data de vencimento;
Possui multa, juros e/ou descontos;
Está dentro do valor máximo que pode ser pago, sendo o valor de R$249.999,99 para ficha de compensação e R$950.000,00 para concessionária, tributos e convênio.

Também checamos se o beneficiário do boleto está apto para receber o pagamento.

📘
Nota
A quantidade de pagamentos parciais que um boleto aceita é configurável no momento do seu registro.

Pré-requisito

Para que seja possível utilizar este endpoint, é necessário que:

O título esteja registrado na CIP (Câmara Interbancária de Pagamentos).

Requisição (Request)

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/bill-payment/validate

--request POST \
--url 'https://api-mtls.sandbox.bankly.com.br/bill-payment/validate' \
--header 'accept: application/json' \
--header 'api-version: 1.0' \
--header 'authorization: Bearer {{Token}}' \
--header 'content-type: application/*+json' \
--header 'x-correlation-id: GUID' \
--data '{
   "code":"{{linha digitável}}"
}'

Autorização

Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:

Scope	Descrição
`payment.validate`	Concede acesso para validar um boleto emitido por outra instituição.

Cabeçalhos (Headers)

Nome	Descrição
`api-version`	Obrigatório. Versão da API. Atualmente estamos na versão 1.0.
`Authorization`	Obrigatório. Token de autorização do tipo Bearer.
`x-correlation-id`	Obrigatório. Informe um GUID, sendo um novo cada requisição.

Parâmetros da rota (Path)

Não é necessário enviar parâmetros no path desta requisição.

Corpo da requisição (Body)

No body, envie o seguintes campo em formato JSON:

Nome	Tipo	Descrição
`code`	`string`	Obrigatório. Linha digitável.

{ 
  "code": "{{linha digitável}}",
}

Resposta (Response)

O status code 200 indicará que a linha digitável foi validada com sucesso.

Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição
`id`	`string`	Identificador único que será necessário no momento de confirmar o pagamento. Importante: o valor retornado neste campo somente será válido por 30 minutos. Após esse tempo, será necessário gerar outro id.
`assignor`	`string`	Nome do cedente.
`recipient`	`object`	Objeto que contém informações sobre o recebedor do pagamento.
`recipient.name`	`string`	Nome do recebedor.
`recipient.documentNumber`	`string`	Número do documento do recebedor.
`payer`	`object`	Objeto que contém informações sobre o cedente.
`payer.name`	`string`	Nome do cedente.
`payer.documentNumber`	`string`	Número do documento do cedente.
`businessHours`	`object`	Objeto que contém informações sobre a faixa de horário permitida para pagamento. Importante: o sistema Bankly somente recebe pagamentos de boletos de depósito ou cobrança emitidos pelo próprio Bankly até as 20h.
`businessHours.start`	`string`	Horário mínimo para realizar o pagamento.
`businessHours.end`	`string`	Horário máximo para realizar o pagamento.
`dueDate`	`string`	Data de vencimento, no formato ISO 8601 - UTC. Importante: no caso de contas concessionárias (contas de consumo, como água, luz, telefone) e de tributos (como IPVA, IPTU), é esperado que este campo retorne nulo.
`settleDate`	`string`	Data em que o pagamento será liquidado, no formato ISO 8601 - UTC. Caso a data de vencimento coincida com feriados ou finais de semana, esse campo informará a data do próximo dia útil.
`nextSettle`	`boolean`	Indica se o título será liquidado no próximo dia útil.
`originalAmount`	`number`	Valor original, sem encargos.
`amount`	`number`	Valor a ser pago. Importante: caso haja alguma incidência de juros, multas ou descontos, o valor a pagar já vem atualizado.
`charges`	`object`	Objeto que contém informações sobre os encargos aplicados na transação. Em caso de pagamentos desfeitos, esse objeto retornará seus campos com valores nulos.
`charges.interestAmountCalculated`	`number`	Valor dos juros.
`charges.fineAmountCalculated`	`number`	Valor da multa.
`charges.discountAmount`	`number`	Valor do desconto.
`maxAmount`	`number`	Máximo valor permitido por pagamento.
`minAmount`	`number`	Mínimo valor permitido por pagamento.
`allowChangeAmount`	`boolean`	Indica se é permitido pagamento parcial (true) ou não (false).
`digitable`	`string`	Linha digitável.

📘
Nota
O campo settleDate apresenta um valor dinâmico, pois exibe a data em que será feita a conciliação do pagamento. Por exemplo, caso o boleto seja pago no dia 03/10/2022 (dia útil) dentro do horário limite, o settleDate apresentará o valor 03/10/2022, que é o dia em que o pagamento será liquidado. No entanto, se o boleto for pago no dia 01/10/2022 (sábado), o settleDate apresentará o valor 03/10/2022, que é o próximo dia útil que permitirá sua liquidação.

{
   "id": "61854f59-7379-4a3b-b699-91899c6f6743",
   "assignor": "Acesso Soluções de Pagamento S.A.",
   "recipient": {
      "name": "Maria Quitéria de Jesus",
      "documentNumber": "099.922.200-74"
   },
   "payer": {
      "name": "Nísia Floresta",
      "documentNumber": "477.426.630-23"
   },
   "businessHours": {
      "start": "07:00",
      "end": "23:00"
   },
   "dueDate": "2022-03-20T00:00:00",
   "settleDate": "2022-03-17T00:00:00",
   "nextSettle": false,
   "originalAmount": null,
   "amount": 895.59,
   "charges": {
      "interestAmountCalculated": 0,
      "fineAmountCalculated": 0,
      "discountAmount": 0
   },
   "maxAmount": 1791.09,
   "minAmount": 0.08,
   "allowChangeAmount": true,
   "digitable": "00190000090280316401743442449222100000000000000"
}

👍
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.

Erros

Este endpoint pode retornar erros específicos, conforme a tabela a seguir:

Status code	Código	Mensagem	Descrição
400	ASSIGNOR_NOT_AUTHORIZED	Non authorized assignor, payment was not completed	A linha digitável não está autorizada no convênio correspondente.
400	BILL_CODE_REQUIRED	Request without barcode or digitable line	O código de barras não pode estar vazio.
400	BANKSLIP_CANCELED	Bankslip has been canceled in the banking institution	Tentativa de validação de um boleto cancelado.
400	INVALID_BILL_BAR_CODE	Invalid bill bar code	O código de barras deve ter: pelo menos 44 caracteres; no máximo 48 caracteres quando iniciar com o número "8"; no máximo 47 caracteres quando não iniciar com o número '8'.
400	PAYMENT_OPERATION_NOT_ALLOWED	Payment not made	Pagamento não efetuado. Não conseguimos receber pagamentos desta instituição. Favor entrar em contato com a instituição emissora e identificar se há restrições de locais de pagamento.
400	MAXIMUM_NUMBER_OF_DAYS_DELAYED_EXCEEDED	Payment not made	Pagamento não efetuado. Número de dias de atraso excedido.
400	DOCUMENT_CANNOT_BE_RECEIVED	Payment cannot be received by this institution	O pagamento não pode ser recebido por essa instituição. Verificar com a instituição emissora do boleto se ele pode ser pago em apenas algumas instituições restritas.
400	EXPIRED_DOCUMENT	Document has expired	A data de pagamento está expirada.
400	PAYMENT_NOT_ALLOWED	Payment not allowed	Pagamento não permitido, favor entrar em contato com a instituição emissora do boleto.
400	CONNECTION_FAILURE	There was a connection problem	Falha na conexão, tente novamente mais tarde.
400	PAYMENT_AWAIT_CONFIRMATION	Payment await confirmation	Pagamento aguardando confirmação, efetivação do pagamento ainda não foi concluída.
400	IMPOSSIBLE_CALCULATE_PAYMENT_AMOUNT_TAX	It was not possible to calculate interest/fees	Problema com o emissor do boleto. Favor contactar a instituição emissora.
400	IMPOSSIBLE_CALCULATE_PAYMENT_AMOUNT	- It was not possible to calculate amount of payment	Problema com o emissor. Favor contactar a instituição emissora.
400	BANKSLIP_SETTLED	Bankslip already been settled	Boleto bancário já quitado.
400	MERCHANT_NOT_ENABLE	The merchant is not considered enabled to receive by the emitting institution	O emissor não é considerado habilitado a receber o pagamento, entre em contato com a instituição emissora.
400	MERCHANT_NOT_REGISTERED	Merchant is not registered	O emissor não está registrado para receber o pagamento, entre em contato com a instituição emissora.
400	MERCHANT_IN_ANALYSIS	Merchant is under analysis by the emitting institution	O emissor não é considerado habilitado a receber o pagamento, entre em contato com a instituição emissora.
400	PARTIAL_PAYMENT_LIMIT_HAS_EXCEEDED	Partial payment limit has exceeded	Tentativa de validação de um boleto que já excedeu a quantidade de pagamentos parciais.
400	DUPLICITY_PAYMENT	Duplicity of a bankslip that does not allow partial payments	Tentativa de pagamento de um boleto que já foi liquidado.
400	PARTIAL_PAYMENT_NOT_ALLOWED	Existing record of a bankslip that does not allow partial payments	Registro existente de boleto bancário que não permite pagamentos parciais.
400	PARTIAL_PAYMENT_BALANCE_HAS_EXCEEDED	Bankslip has exceed the available balance for partial payment for calculation model	O boleto ultrapassou o saldo disponível para pagamento parcial para modelo de cálculo.
400	PAYMENT_AFTER_EXPIRANCY_DATE_NOT_ALLOWED	Bankslip can not be paid after it expiracy date	O boleto bancário não pode ser pago após a data de vencimento.
400	SETTLEMENT_DATE_AFTER_DUE_DATE	A payment is being made outside the settlement schedule, and the next settlement window has expired	O pagamento está sendo realizado fora da grade horária de liquidação, e a próxima janela de liquidação já expirou.
400	PAYMENT_FOR_BENEFICIARY_NOT_ALLOWED	A payment for the informed beneficiary is not allowed	Problema com o emissor do boleto. Favor contactara instituição emissora.
400	PAYMENT_PROVIDER_ERROR	An error ocurred while executing operation, please contact the provider for further information	Ocorreu um erro durante a execução da operação. Entre em contato com o provedor para obter mais informações.
400	INTERMITTENCE_OCCURRED	An intermittent issue has occurred. Please try again later.	O serviço está apresentando instabilidade. Tente novamente em alguns minutos.
400	REQUEST_WITHOUT_CORRELATION_ID	Request without correlation id	`correlationId` não informado.
404	BAR_CODE_NOT_FOUND	Bar Code not found	Código de barras não encontrado na CIP/NUCLEA. É possível que o boleto ainda não tenha sido registrado pela instituição emissora.
404	TRANSACTION_NOT_FOUND	Transaction not found	Transação não foi encontrada. Caso a linha digitável esteja correta, entre em contato com a instituição emissora para mais detalhes.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400.

🚧
Importante
Por segurança, o parceiro tem até 20 minutos a partir da validação para confirmar o pagamento. Caso contrário, irá receber o erro 404 - BILL_PAYMENT_NOT_FOUND_FOR_SUPPLIED_ID e precisará realizar a validação novamente para prosseguir.

Eventos

Este endpoint não possui eventos relacionados a ele.