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é-requisitos

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 / Query)

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:

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.

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

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints que acompanham os erros 400 (se houver).

Eventos

Este endpoint não possui eventos relacionados a ele.