Consultar Chaves Pix Externa (DICT)
Consultar uma chave Pix para uma conta
Com essa chamada você consultará uma chave externa Pix e consequentemente irá gerar um endtoend para uma futura transação.
GlossárioDICT -> 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
- Realizar autenticação na API - [API Reference]
- 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
{
"version": "1.0.0",
"status": "CONFIRMED",
"body": {
"keyType": "string",
"key": "string",
"account": {
"participant": "30306294",
"branch": "0001",
"account": "10545584",
"accountType": "TRAN",
"createDate": "2020-11-03T06:30:00-03:00"
},
"owner": {
"type": "NATURAL_PERSON",
"documentNumber": "93179848006",
"name": "Carlos Silva",
"tradeName": "Carlos Silva"
},
"endtoEndId": "string",
"creationDate": "2025-04-09T19:18:02.819Z",
"keyOwnershipDate": "2025-04-09T19:18:02.819Z",
"openClaimCreationDate": "2025-04-09T19:18:02.819Z",
"statistics": {
"ownerStatistics": {
"spi": {
"watermark": "2025-04-09T19:18:02.819Z",
"settlements": {
"d90": 0,
"m12": 0,
"m60": 0
}
},
"fraudMarkers": {
"watermark": "2025-04-09T19:18:02.819Z",
"applicationFrauds": {
"d90": 0,
"m12": 0,
"m60": 0
},
"muleAccounts": {
"d90": 0,
"m12": 0,
"m60": 0
},
"scammerAccounts": {
"d90": 0,
"m12": 0,
"m60": 0
},
"otherFrauds": {
"d90": 0,
"m12": 0,
"m60": 0
},
"unknownFrauds": {
"d90": 0,
"m12": 0,
"m60": 0
},
"totalFraudTransactionAmount": {
"d90": 0,
"m12": 0,
"m60": 0
},
"distinctFraudReporters": {
"d90": 0,
"m12": 0,
"m60": 0
}
},
"infractionReports": {
"watermark": "2025-04-09T19:18:02.819Z",
"openReports": 0,
"openReportsDistinctReporters": 0,
"rejectedReports": {
"d90": 0,
"m12": 0,
"m60": 0
}
},
"entries": {
"watermark": "2025-04-09T19:18:02.819Z",
"registeredAccounts": 0,
"distinctAccounts": {
"d90": 0,
"m12": 0,
"m60": 0
}
}
},
"keyStatistics": {
"spi": {
"watermark": "2025-04-09T19:18:02.819Z",
"settlements": {
"d90": 0,
"m12": 0,
"m60": 0
}
},
"fraudMarkers": {
"watermark": "2025-04-09T19:18:02.819Z",
"applicationFrauds": {
"d90": 0,
"m12": 0,
"m60": 0
},
"muleAccounts": {
"d90": 0,
"m12": 0,
"m60": 0
},
"scammerAccounts": {
"d90": 0,
"m12": 0,
"m60": 0
},
"otherFrauds": {
"d90": 0,
"m12": 0,
"m60": 0
},
"unknownFrauds": {
"d90": 0,
"m12": 0,
"m60": 0
},
"totalFraudTransactionAmount": {
"d90": 0,
"m12": 0,
"m60": 0
},
"distinctFraudReporters": {
"d90": 0,
"m12": 0,
"m60": 0
}
},
"infractionReports": {
"watermark": "2025-04-09T19:18:02.819Z",
"openReports": 0,
"openReportsDistinctReporters": 0,
"rejectedReports": {
"d90": 0,
"m12": 0,
"m60": 0
}
},
"entries": {
"watermark": "2025-04-09T19:18:02.819Z",
"registeredAccounts": 0,
"distinctAccounts": {
"d90": 0,
"m12": 0,
"m60": 0
}
}
}
},
"isSameTaxId": true
}
}Tabela com os Campos de Consulta DICT
Campo | Descrição |
|---|---|
keyType | Tipo da Chave de Endereçamento.
|
key | Chave identificador da Conta Transacional |
account | Objeto com informações da Conta Recebedora |
owner | Objeto com informações do Dono da Chave Recebedora |
endtoEndId | Identificador único da transação de pagamento. Gerado pelo PSI ou PSP Pagador, será informado ao DICT, ao SPI e ao PSP Recebedor |
creationDate | Data de criação da Chave |
keyOwnershipDate | Data da última reinvidicação ou portabilidade completa |
openClaimCreationDate | Data da última reinvidicação ou portabilidade iniciada |
statistics | Objeto de dados estatísticos relacionados ao usuário pessoa física ou pessoa jurídica. As estatísticas só serão incluídas caso a chave pertença a um PSP externo, pois a consulta é realizada no DICT do Bacen. |
Account | |
|---|---|
participant | ISPB do PSP Recebedor |
branch | Número da Agência Recebedora |
account | Número da Conta Recebedora |
accountType | Tipo da Conta Recebedora. |
createDate | Data de criação da Conta Recebedora |
Owner | |
|---|---|
type | Tipo Pessoa Recebedora.
|
documentNumber | Número de Documento (CPF ou CNPJ) Recebedora |
name | Razão Social ou Nome Completo do Recebedor |
tradeName | Nome Fantasia do Recebedor |
| Statistics | |
|---|---|
| ownerStatistics | Dados estatísticos relacionados ao usuário |
| keyStatistics | Dados estatísticos relacionados a chave |
| Dados Estatísticos | |
|---|---|
| spi | Grupo de Estatisticas referente a Transações no SPI |
| fraudMarkers | Grupo de Estatisticas referente a Marcações de Fraude |
| infractionReports | Grupo de Estatisticas referente a Notificações de Infração |
| entries | Grupo de Estatisticas referente a Contas |
| Contadores de Fraude | |
|---|---|
| applicationFrauds | Contadores das marcações de fraude do tipo Falsidade Ideológica. |
| muleAccounts | Contadores das marcações de fraude do tipo Conta Laranja. |
| scammerAccounts | Contadores das marcações de fraude do tipo Conta do Fraudador. |
| otherFrauds | Contadores das marcações de fraude do tipo Outra. |
| unknownFrauds | Contadores das marcações de fraude sem classificação de tipo (inclui o tipo “Desconhecida”, utilizado p/ marcações de fraude oriundas de notificações de infração fechadas na API DICT 1.9.1). |
| settlements | Contadores das transações realizadas no SPI |
| totalFraudTransactionAmount | Contadores do valor total das marcações de fraude associadas a transações liquidadas no SPI |
| distinctFraudReporters | Contadores com o número de participantes distintos que geraram marcações de fraude. |
| openReports | Número de notificações de infração ainda não concluídas e nem canceladas |
| openReportsDistinctReporters | Número de participantes distintos criadores de notificações de infração ainda não concluídas e nem canceladas |
| rejectedReports | Contadores de notificações de infração concluídas com rejeição |
| registeredAccounts | Contadores de contas da pessoa associadas a chaves atualmente registradas |
| watermark | Data e hora do último evento considerado na atualização dos dados antifraude |
Error 400
{
"version": "1.0.0",
"status": "ERROR",
"error": {
"errorCode": "CBE177",
"message": "Operação não permitida. Conta esta bloqueada"
}
}Tabela de errorCode
| Code | Message |
|---|---|
| CBE091 | É necessário informar pelo menos um dos campos: id, clientCode, ou endtoendId. |
| CBE039 | Account invalido. |
| CBE175 | Cadastro de chave não permitido. Verifique o formato da chave informada |
| CBE041 | Account possui tamanho maximo de 20 caracteres |
| CBE174 | O Campo key não pode ultrapassar 77 caracteres |
| CBE176 | Operação não permitida. Conta esta encerrada |
| CBE177 | Operação não permitida. Conta esta bloqueada |
| CBE190 | Operação Não permitida. Chave não esta vinculada a essa conta. |
| CPD0013 | Chave Pix com dados restritos por marcação de fraude |
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"
},Updated 14 days ago