Consulta por código de autenticação

Este endpoint permite que o cliente do parceiro Bankly obtenha todos os detalhes de um pagamento específico (completado ou não) por meio de seu código de autenticação (authenticationCode).

Pré-requisito

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

O parceiro possua o authenticationCode gerado após a confirmação do pagamento.

Requisição (Request)

Requisição HTTP

GET https://sandbox.hiperbanco.com.br/Payments/detail/{{accountBranch}}/{{accountNumber}}/{{authenticationCode}}

--request GET 'https://sandbox.hiperbanco.com.br/Payments/detail/{{accountBranch}}/{{accountNumber}}/{{authenticationCode}}' \
--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
`bankBranch`	`path`	Obrigatório. Número da agência do banco do pagador.
`bankAccount`	`path`	Obrigatório. Número da conta do pagador.
`authenticationCode`	`path`	Obrigatório. Código de autenticação do pagamento que se deseja consultar. O valor pode ser obtido no retorno da requisição de confirmação de pagamento.

Corpo da requisição (Body)

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

Resposta (Response)

O status code 200 indicará que a solicitação foi aceita com sucesso e trará as informações do pagamento.

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

Nome	Tipo	Descrição
`authenticationCode`	`string`	Id de confirmação da transação.
`bankAccount`	`string`	Número da conta do pagador.
`bankBranch`	`string`	Número da agência do pagador.
`description`	`string`	Descrição do pagamento.
`paymentDate`	`string`	Data do pagamento, no formato ISO 8601 - UTC.
`status`	`string`	Situação do pagamento.
`companyKey`	`string`	Chave identificadora da companhia.
`documentNumber`	`string`	Número do documento do pagador.
`confirmedAt`	`string`	Data da confirmação do pagamento, no formato ISO 8601 - UTC.
`digitable`	`string`	Linha digitável do boleto.
`amount`	`number`	Valor pago.
`originalAmount`	`number`	Valor original, sem encargos.
`totalAmount`	`number`	Valor total pago, incluindo encargos.
`assignor`	`string`	Nome do cedente do boleto.
`recipientDocument`	`string`	Número do documento do recebedor.
`recipientName`	`string`	Nome do recebedor. do pagamento.
`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 de juros calculado.
`charges.fineAmountCalculated`	`number`	Valor de multa calculado.
`charges.discountAmount`	`number`	Valor de desconto aplicado.
`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.
`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.

{
    "authenticationCode": "ab3db1a9-cb3d-49b1-8291-6bc85fe12713",
    "bankAccount": "1104835921",
    "bankBranch": "0001",
    "description": "reiciendis",
    "paymentDate": "21/08/2025 20:22:47",
    "status": "Completed",
    "companyKey": "SDB2_HIPERBANCO",
    "documentNumber": "50300633859100",
    "confirmedAt": "21/08/2025 20:22:58",
    "digitable": "34191090080025732445903616490003691150000020000",
    "amount": 200.001,
    "originalAmount": 200.001,
    "totalAmount": 200.001,
    "assignor": "BANCO ITAU S.A.",
    "recipientDocument": "87.754.347/0001-08",
    "recipientName": "BENEFICIARIO AMBIENTE HOMOLOGACAO",
    "charges": {
        "interestAmountCalculated": 0.001,
        "fineAmountCalculated": 0.001,
        "discountAmount": 0.001
    },
    "settleDate": "22/08/2025 03:00",
    "dueDate": "20/09/2025 03:00"
}

Status

Status	Descrição
`Created`	Significa que o título já foi validado e o pagamento está sendo iniciado.
`Completed`	O pagamento do título foi confirmado.
`Confirmed`	O pagamento do titulo foi compensado e o valor já consta na conta do beneficiário
`Canceled`	O pagamento foi cancelado.

Erros

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

Código	Nome	Tipo	Descrição
`400`	`FORBIDDEN_ACCESS`	`The user is authenticated but does not have permission to perform the requested action.`	O usuário está autenticado, mas não tem permissão para executar a ação solicitada. Esse erro ocorre quando os dados da conta autenticada não correspondem à conta que efetuou o pagamento.
`403`	`AUTHORIZATION_ERROR`	`Invalid credentials`	Falha na autenticação do usuário.
`403`	`ASSIGNOR_NOT_AUTHORIZED`	`Non authorized assignor, payment was not completed`	Falha na autenticação do usuário.
`404`	`NOT_FOUND_BILL_PAYMENT_BY_AUTHENTICATION_CODE`	`Not found bill payment by authentication code`	Não foram encontrados pagamentos com esse authenticationCode.

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.