Consulta de chaves para transferência

Antes de realizar uma transação para uma chave Pix, é preciso verificar informações vinculadas a essa chave.

Para isso, realiza-se uma consulta no DICT, por meio da URL e de parâmetros que serão descritos nesta documentação.

Essa consulta abrange todas as chaves cadastradas no Bacen, não apenas aquelas vinculadas às contas Bankly.

Condições para consulta

Como mecanismo de prevenção a ataques de leitura, o DICT possui um controle de requisições baseado em consultas de chaves que não possuam liquidação e consultas inválidas.

Caso o Bankly identifique a recorrência de consultas sem vínculo com transações Pix, o consumo do serviço será bloqueado.

❗️

Atenção

O DICT não deve ser utilizado para consulta cadastral e nem para qualquer outra finalidade que não seja transacionar para uma chave Pix.

Etapas

Endpoint

Para consumo deste endpoint, é preciso preencher os seguintes campos obrigatórios:

• x-bkly-pix-user-id: informar o número do documento do usuário que está consultando a chave;
• x-correlation-id: informe um GUID v4, gerado randomicamente. A cada requisição, deve-se gerar um novo GUID v4;
• addressingKeyValue: esse parâmetro pode ser informado com:
  • CPF: 11 dígitos, sem formatação;
  • CNPJ: 14 dígitos, sem formatação;
  • E-mail: todos os caracteres em minúsculo. Tamanho máximo de 72 caracteres;
  • 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.: +5511912345678;
  • EVP: tamanho máximo de 36 caracteres. Exemplo: 123e4567-e89b-12d3-a456-426655440000.

curl --request GET \ 
     --url 'https://api-mtls.sandbox.bankly.com.br/pix/entries/{{addressingKeyValue}}' \
     --header 'Accept: application/json' \
     --header 'api-version: 1' \
     --header 'x-bkly-pix-user-id: {{userDocument}}' \
     --header 'x-correlation-id: {{correlationId}}' \ 
     --header 'Authorization: Bearer {{accessToken}}'

🚧

Importante

Só será possível realizar a consulta por chave se o payer x-bkly-pix-user-id estiver cadastrado em nossa base de dados. Caso contrário, será retornado o erro 403 - FORBIDDEN.

Retorno

A consulta de chave no DICT retornará:

• endToEndId: identificador único do Pix. Ele será utilizado quando o parceiro realizar uma transação de Pix cash-out (saída de dinheiro da conta);
• addressingKey: informa o tipo de chave de endereçamento e seu valor;
• holder: seus subcampos trazem os dados do titular da conta;
• status: descreve o status da chave de endereçamento, que pode ser:
  • 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.
• createdAt: exibe a data de criação da chave;
• ownedAt: informa a última data em que a chave foi vinculada a uma conta.

📘

Nota

O campo name retornará o nome do documento de cadastro, e não o nome social

new

{
    "endToEndId": "E1314008820210629151241054156224",
    "addressingKey": {
        "type": "CPF",
        "value": "***123456**"
    },
    "holder": {
        "type": "CUSTOMER",
        "name": "Peter Parker",
        "socialName": "Carol Denvers",
        "document": {
            "value": "***123456**",
            "type": "CPF"
        }
    },
    "status": "OWNED",
    "createdAt": "2020-11-06T01:07:12.351+00:00",
    "ownedAt": "2020-11-06T01:07:12.337+00:00"
}

👍

Dica

Para consultar as chaves de endereçamento vinculadas a uma conta, confira a documentação Consulte as chaves de endereçamento de uma conta.

Erros