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á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

{
  "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

CampoDescrição
keyTypeTipo da Chave de Endereçamento.

- CPF
- CNPJ
– EMAIL
– PHONE
– EVP
keyChave identificador da Conta Transacional
accountObjeto com informações da Conta Recebedora
ownerObjeto com informações do Dono da Chave Recebedora
endtoEndIdIdentificador único da transação de pagamento. Gerado pelo PSI ou PSP Pagador, será informado ao DICT, ao SPI e ao PSP Recebedor
creationDateData de criação da Chave
keyOwnershipDateData da última reinvidicação ou portabilidade completa
openClaimCreationDateData da última reinvidicação ou portabilidade iniciada
statisticsObjeto de dados estatísticos relacionados ao usuário pessoa física ou pessoa jurídica.
Account
participantISPB do PSP Recebedor
branchNúmero da Agência Recebedora
accountNúmero da Conta Recebedora
accountTypeTipo da Conta Recebedora.
– Conta Corrente - CACC
– Conta Salário - SLRY
– Conta Poupança - SVGS
– Conta de Pagamento - TRAN
createDateData de criação da Conta Recebedora
Owner
typeTipo Pessoa Recebedora.

- Pessoa Física - NATURAL_PERSON
- Pessoa Jurídica - LEGAL_PERSON
documentNumberNúmero de Documento (CPF ou CNPJ) Recebedora
nameRazão Social ou Nome Completo do Recebedor
tradeNameNome Fantasia do Recebedor
Statistics
ownerStatisticsDados estatísticos relacionados ao usuário
keyStatisticsDados estatísticos relacionados a chave
Dados Estatísticos
spiGrupo de Estatisticas referente a Transações no SPI
fraudMarkersGrupo de Estatisticas referente a Marcações de Fraude
infractionReportsGrupo de Estatisticas referente a Notificações de Infração
entriesGrupo de Estatisticas referente a Contas
Contadores de Fraude
applicationFraudsContadores das marcações de fraude do tipo Falsidade Ideológica.
muleAccountsContadores das marcações de fraude do tipo Conta Laranja.
scammerAccountsContadores das marcações de fraude do tipo Conta do Fraudador.
otherFraudsContadores das marcações de fraude do tipo Outra.
unknownFraudsContadores 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).
settlementsContadores das transações realizadas no SPI
totalFraudTransactionAmountContadores do valor total das marcações de fraude associadas a transações liquidadas no SPI
distinctFraudReportersContadores com o número de participantes distintos que geraram marcações de fraude.
openReportsNúmero de notificações de infração ainda não concluídas e nem canceladas
openReportsDistinctReportersNúmero de participantes distintos criadores de notificações de infração ainda não concluídas e nem canceladas
rejectedReportsContadores de notificações de infração concluídas com rejeição
registeredAccountsContadores de contas da pessoa associadas a chaves atualmente registradas
watermarkData 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

CodeMessage
CBE091É necessário informar pelo menos um dos campos: id, clientCode, ou endtoendId.
CBE039Account invalido.
CBE175Cadastro de chave não permitido. Verifique o formato da chave informada
CBE041Account possui tamanho maximo de 20 caracteres
CBE174O Campo key não pode ultrapassar 77 caracteres
CBE176Operação não permitida. Conta esta encerrada
CBE177Operação não permitida. Conta esta bloqueada
CBE190Operação Não permitida. Chave não esta vinculada a essa conta.