Consulta de chaves de uma conta para transação

Requisição (Request)

Requisição HTTP

GET https://sandbox.hiperbanco.com.br/pix/validate/{{addressingKeyValue}}

--request GET 'https://sandbox.hiperbanco.com.br/pix/validate/{{addressingKeyValue}}' \
--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 JSO

⚠️
Importante
Só será possível realizar a consulta por chave se o Número do documento do usuário que está fazendo a requisição estiver cadastrado em nossa base de dados. Caso contrário, será retornado o erro 403 - FORBIDDEN.

Parâmetros da rota (Path)

No path desta requisição envie os seguintes campos:

Nome	Tipo	Descrição
addressingKeyValue	path	Obrigatório. Valor da chave de endereçamento a ser consultada. Veja na tabela a seguir as possibilidades de preenchimento.

Chave de endereçamento

Chave	Instrução de preenchimento
CPF	11 dígitos, sem caracteres especiais.
CNPJ	14 dígitos, sem caracteres especiais.
EMAIL	Todos os caracteres em minúsculo. Tamanho máximo de 72 caracteres.
PHONE	Número de telefone celular, composto por símbolo ‘+’, seguido pelo código do país, DDD e número de celular com até nove dígitos. Ex.: +5523415162342.
EVP	Tamanho máximo de 36 caracteres. Exemplo: 123e4967-e89b-12d3-a456-426655440000.

Corpo da requisição (Body)

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

Resposta (Response)

O status code 200 indicará sucesso na consulta.Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição
endToEndId	string	Identificador único do Pix. Ele será utilizado quando o parceiro realizar um pagamento ou transferência via Pix.
addressingKey	object	Objeto com informações da chave de endereçamento.
addressingKey.type	string	Tipo de chave, que pode ser "CPF", "CNPJ", "PHONE", "EMAIL" ou "EVP".
addressingKey.value	string	Valor da chave de endereçamento.
account	object	Objeto com informações da conta associada.
account.bank	object	Objeto com informações do banco.
account.bank.ispb	string	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
holder	object	Objeto com informações do titular da chave.
holder.type	string	Tipo de titular da conta, que pode ser "CUSTOMER" ou "BUSINESS".
holder.name	string	Nome completo do titular da chave.
holder.socialName	string	Nome pelo qual o titular gostaria de ser chamado. Saiba mais consultando a Cartilha do nome social. Este campo somente será retornado em caso de consulta de chave de pessoa física.
holder.tradingName	string	Nome fantasia da empresa. Este campo somente será retornado em caso de consulta de chave de pessoa jurídica.
holder.document	object	Objeto com informações do documento do titular.
holder.document.value	string	Número do documento.
holder.document.type	string	Tipo do documento, que pode ser "CPF" ou "CNPJ”.
status	string	Descreve o status da chave de endereçamento.
createdAt	string	Data de criação da chave, no formato ISO 8601 - UTC.
ownedAt	string	Última data em que a chave foi vinculada a uma conta, no formato ISO 8601 - UTC.

⚠️
Importante
O campo endToEndId possui duração de 15 minutos e só poderá ser utilizado em uma única transferência.

{
    "endToEndId": "E13140088202507090058341B5EC16CC",
    "addressingKey": {
        "type": "CPF",
        "value": "39182944717"
    },
    "account": {
        "bank": {
            "ispb": "13140088"
        }
    },
    "holder": {
        "type": "CUSTOMER",
        "name": "Alyson Almeida Ferreira",
        "socialName": "Alyson Almeida",
        "document": {
            "value": "***829447**",
            "type": "CPF"
        }
    },
    "status": "OWNED",
    "createdAt": "2025-06-16T13:26:11.604-03:00",
    "ownedAt": "2025-06-16T13:26:11.604-03:00"
}

{
    "endToEndId": "E1314008820250709011790C6A8FC2EE",
    "addressingKey": {
        "type": "CNPJ",
        "value": "86046117747170"
    },
    "account": {
        "bank": {
            "ispb": "13140088"
        }
    },
    "holder": {
        "type": "BUSINESS",
        "tradingName": "Costa LTDA",
        "document": {
            "value": "***461177471**",
            "type": "CNPJ"
        },
        "socialName": "Costa LTDA"
    },
    "status": "OWNED",
    "createdAt": "2025-07-08T22:16:19.307-03:00",
    "ownedAt": "2025-07-08T22:16:19.307-03:00"
}

Status da chave de endereçamento

Status	Descrição
OWNED	A chave pertence à conta.
EXCLUDED	A chave foi excluída e não está mais vinculada a nenhuma conta.
LOCKED_BY_CLAIM	A chave está bloqueada por um processo de portabilidade/reivindicação e não pode ser alterada ou excluída.

Erros

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

Status Code	Código	Mensagem	Descrição
404	ENTRY_NOT_FOUND	Entry not found.	Chave não encontrada.
408	REQUEST_TOOK_TOO_LONG_TO_RESPOND	Request took too long to respond. Please, wait 1 minute to try again.	A solicitação demorou muito para ser respondida. Aguarde alguns instantes para tentar novamente.
422	INVALID_USER_ID	Ensure that the x-bkly-pix-user-id header is a valid CPF or CNPJ document.	User id inválido. Verifique se o header x-bkly-pix-user-id é um CPF ou CNPJ válido.
422	PERMISSION_NOT_GRANTED	Permission not granted to perform the operation.	Permissão não concedida para realizar a operação.
422	MAXIMUM_ENTRIES_COUNT_REGISTERED_FOR_ACCOUNT	Account has reached the maximum entries count registered.	A quantidade de chaves registradas já atingiu o limite máximo.
422	ENTRY_ALREADY_EXISTS_TO_SAME_ACCOUNT	Entry already in use to same account. Consider making change account request.	Chave já em uso na mesma conta.
422	ENTRY_ALREADY_EXISTS_TO_ANOTHER_HOLDER	Entry already exists to another holder. Consider making claim request.	Chave já cadastrada por outro titular. Considere fazer uma solicitação de reivindicação.
422	ENTRY_ALREADY_EXISTS_TO_SAME_OWNER_INTO_ANOTHER_PLAYER	Entry already in use to same owner in another player. Consider making portability request.	Chave já em uso pelo mesmo dono em outra instituição financeira. Considere fazer o pedido de portabilidade.
422	ENTRY_LOCKED_BY_CLAIM	Entry is locked when claim request is being process.	A chave é bloqueada quando a solicitação de reivindicação está sendo processada.
422	REQUEST_NOT_ALLOWED_OUT_OF_BUSINESS_PERIOD	Request not not allowed out of business period.	Solicitação não permitida fora do período comercial.
422	EVP_ENTRY_CANNOT_REGISTER_SHORT_INTERVAL	Entry of type EVP cannot be registered in a short interval of time. Please wait a minute and try again.	Não é permitido cadastrar mais de uma chave do tipo EVP em um curto intervalo de tempo.
422	ANY_ENTRY_FOUND_TO_ACCOUNT	Not exists entries to account.	Nenhuma chave encontrada para a conta.
422	ANY_ENTRY_FOUND_TO_HOLDER	Not exists entry to holder.	Nenhuma chave encontrada para o titular.
422	ENTRY_ALREADY_EXISTS_TO_SAME_HOLDER_AND_ANOTHER_ACCOUNT	Entry already in use to same holder but to another account. Consider making portability request.	Chave já em uso pelo mesmo titular, mas em outra conta. Considere fazer o pedido de portabilidade.
429	RATE_LIMIT_REQUESTS_EXCEEDED	Rate limit exceeded and blocked by provider.	Limite de requisições excedido e bloqueado pelo provedor (trinta requisições por minuto no máximo e quatro requisições por segundo).
429	RATE_LIMIT_REQUESTS_EXCEEDED_BY_BACEN	Rate limit requests exceeded and blocked by BACEN.	Limite de requisições excedido e bloqueado pelo Bacen.

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.