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.
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).
Usuário deverá está autenticado

Requisição (Request)

Requisição HTTP

PATCH https://sandbox.hiperbanco.com.br/Payments/validate/{{code}}

--request PATCH 'https://sandbox.hiperbanco.com.br/Payments/validate/{{code}}' \
--header 'version: cutting-edge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}'

Cabeçalhos (Headers)

Nome	Propriedade	Descrição
version	cutting-edge	Essa propriedade garante que o response da API seja retornado no formato JSON
Authorization	Bearer token	Obrigatório. Token de autorização do tipo Bearer.

Parâmetros da rota (Path)

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

Corpo da requisição (Body)

Não é necessário enviar campos no body desta requisição.

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 Hiperbanco somente recebe pagamentos de boletos de depósito ou cobrança emitidos pelo próprio Hiperbanco 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.
`nextBusinessDay`	`string`	Próximo dia útil após a data de vencimento.

📘
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": "b985967b-a0ed-4810-addd-ec100b128171",
    "assignor": "BANCO ITAU S.A.",
    "recipient": {
        "name": "BENEFICIARIO AMBIENTE HOMOLOGACAO",
        "documentNumber": "87.754.347/0001-08"
    },
    "payer": {
        "name": "PAGADOR AMBIENTE DE HOMOLOGACAO",
        "documentNumber": "698.447.801-44"
    },
    "businessHours": {
        "start": "07:00",
        "end": "20:00"
    },
    "dueDate": "2025-09-20T00:00:00",
    "settleDate": "2025-08-22T00:00:00",
    "nextSettle": true,
    "originalAmount": 200,
    "amount": 200,
    "charges": {
        "interestAmountCalculated": 0,
        "fineAmountCalculated": 0,
        "discountAmount": 0
    },
    "maxAmount": 200,
    "minAmount": 200,
    "allowChangeAmount": false,
    "digitable": "34191090080025732445903616490003691150000020000",
    "nextBusinessDay": "2025-08-21T23:22:34.463Z"
}

Erros

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

Código	Nome	Tipo	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:<br><br>- pelo menos 44 caracteres;<br>- no máximo 48 caracteres quando iniciar com o número "8";<br>- 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 que acompanham os erros 400 (se houver).

⚠️
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.