Consultar Chaves Pix Externa (DICT)

Com essa chamada você consultará uma chave externa Pix e consequentemente irá gerar um endtoend para uma futura transação.

📘

Glossário

DICT -> O Diretório de Identificadores de Contas Transacionais - é o serviço do arranjo Pix que permite buscar detalhes de contas transacionais com chaves de endereçamento mais convenientes para quem faz um pagamento. Entre os tipos de chave atualmente disponíveis estão CPF, CNPJ, telefone, e-mail e EVP.

Entenda o comportamento desse endpoint

Esse endpoint adota um “sistema de baldes e fichas" em conformidade com o Manual Operacional do DICT (seção 13: “mecanismos de prevenção a ataques de leitura”).

Para entender o funcionamento, acesse aqui.

Passos para Integrar

1. Realizar autenticação na API - [API Reference]
2. Consultar Chaves Pix Externa- [API Reference]

Consultar chaves Pix Externa (DICT)

Chaves para Testes

CPF -> 77517432125

Email-> [email protected]

Telefone -> +5532976886942

Verificação de Propriedade da Chave Pix

Ao enviar o parâmetro ownerTaxId na requisição de consulta, validaremos se o proprietário da chave é o mesmo que o titular da conta, o que permitirá identificar se a transferência via Pix é feita entre titulares iguais ou não.

Retorno do campo isSameTaxId:
Na resposta da consulta, temos o campo isSameTaxId, que indicará se o taxId da chave é igual ao ownerTaxId enviado na requisição:

true: Se os documentos forem iguais.
false: Se os documentos forem diferentes.

cURL da chamada

curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/baas/v2/pix/dict/entry/external/30054065526?key=77517432125&ownerTaxId=19702369061&includeStatistics=true' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}'

Exemplo de retorno

👍

Sucesso 200

{
  "status": "SUCCESS",
  "body": {
    "keyType": "EMAIL",
    "key": "[email protected]",
    "account": {
      "participant": "18236120",
      "branch": "0",
      "account": "********",
      "accountType": "********",
      "createDate": null
    },
    "owner": {
      "type": "********",
      "documentNumber": "***778477**",
      "name": "teste celcoin"
    },
    "endtoEndId": "E139358932026032313566ZQX3kOHGyf",
    "creationDate": null,
    "keyOwnershipDate": null,
    "openClaimCreationDate": null,
    "statistics": null,
    "isSameTaxId": false
  },
  "version": "1.0.0"
}

Tabela com os Campos de Consulta DICT

❗

Error 400

{
  "version": "1.0.0",
  "status": "ERROR",
  "error": {
    "errorCode": "CBE177",
    "message": "Operação não permitida. Conta esta bloqueada"
  }
}

Tabela de errorCode

❗️

Com a alteração definida pela Circular BCB nº 501, o Banco Central passou a impedir, a partir de 04/10/2025, o retorno de dados de chaves Pix que estejam marcadas como suspeitas de fraude no DICT. Isso significa que, sempre que uma nova chave com essa marcação for consultada, o DICT não retornará informações do titular ou da conta vincula

Exemplo de retorno com chave marcada com fraude

{
  "version": "1.0.0",
  "status": "ERROR",
  "error": {
    "errorCode": "CPD0013",
    "message": "Chave Pix com dados restritos por marcação de fraude"
  },

End To End ID no Pix - Entendendo como Funciona

A cada consulta de chave Pix realizada, a Celcoin irá gerar e devolver no response um EndToEndId, que deverá ser utilizado na hora de efetivar a transação.

O End To End ID é o identificador único entre todo o arranjo, seguindo um padrão definido pelo próprio Banco Central. A principal forma de identificar uma transação Pix, é através do End To End ID da mesma, que trafega na Instituição Pagadora, Instituição Recebedora e no Banco Central.

Cada EndToEndID tem validade máxima de 12 horas após o momento de geração do mesmo.