Validar a chave antes de pagar
Explica por que consultar o titular da chave no DICT antes de enviar um Pix.
O que é o DICT
O DICT (Diretório de Identificadores de Contas Transacionais) é a base central mantida pelo Banco Central que guarda todas as chaves Pix registradas no Brasil. Através dele, você valida que uma chave existe e recupera os dados do destinatário antes de fazer um pagamento.
Por que consultar o DICT antes de pagar?
- Confirma que a chave existe e está ativa, evitando pagamentos para chaves inválidas ou inexistentes.
- Valida o titular que o usuário disse ser o destinatário, agindo como camada de anti-fraude.
- Mostra o nome do recebedor para confirmação antes de concluir a transação (UX melhor).
- Reduz custos operacionais evitando tentativas de pagamento que falhariam.
Fluxo recomendado
Qual rota usar
Duas rotas consultam o DICT: GET /pix/key e GET /user/dict. As duas chamam o mesmo serviço e compartilham o mesmo cache e a mesma cota de consulta da conta: uma chamada em uma rota consome a cota da outra e aproveita o resultado já cacheado. A diferença está no escopo do token e na quantidade de campos.
| Item | GET /pix/key | GET /user/dict |
|---|---|---|
| Parâmetro | pixKey | key |
| Escopo do token | DEPOSIT ou WITHDRAW | WITHDRAW |
| Campos devolvidos | 10, incluindo branch, accountNumber e institutionCode | 7 |
document | Dígitos crus | Formatado (000.000.000-00) |
Nenhuma das duas oculta dígito: a diferença é só a pontuação de CPF/CNPJ.
Só o escopo WITHDRAW atende às duas. Para confirmar o titular na tela antes de pagar, GET /user/dict basta e devolve menos dado sensível.
Quando consultar
A consulta DICT é obrigatória antes de:
- Pagamentos via chave Pix (
POST /withdraw). - Primeira transferência para um novo destinatário.
- Pagamentos de valor alto.
- Transações fora do padrão habitual do usuário.
Em alguns casos a consulta pode ser opcional:
- Pagamentos recorrentes para o mesmo destinatário cujos dados já foram validados.
- Retentativa imediata após falha técnica.
Nesses casos, é aceitável usar dados em cache por período limitado.
Tratamento de erros
Os erros da consulta seguem o envelope padrão da API; os códigos específicos de chave Pix/DICT, com o que fazer em cada um, estão em Códigos de erro.
Segurança
O DICT confirma que a chave existe, mas isso não garante que o pagamento é legítimo. Sempre combine a consulta com outras validações anti-fraude.
Ao mostrar os dados do destinatário para o usuário, mascare dados sensíveis como CPF e CNPJ:
- CPF:
123.***.***-01 - CNPJ:
12.345.***/**01-00
Implemente rate limiting por usuário nas consultas DICT e monitore buscas excessivas, que podem indicar tentativa de enumeração de chaves. Os dados retornados pelo DICT são para validação momentânea e não devem ser persistidos sem necessidade.
Limites e considerações
| Item | Informação |
|---|---|
| Rate limit | Cota por conta, compartilhada entre GET /pix/key e GET /user/dict |
| Cache | Resposta cacheada por até 24h e reaproveitada pelas duas rotas |
| Disponibilidade | DICT pode ficar indisponível em manutenção do Bacen |
| Dados | O nome pode vir truncado segundo regras do Bacen |