Consulta DICT
Antes de pagar, consulte no DICT do Banco Central se a chave Pix existe e confira o nome do titular, evitando que o dinheiro pare na conta errada.
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
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 | Consulte os limites da sua conta |
| Cache | Os dados podem ser cacheados por até 24h |
| Disponibilidade | DICT pode ficar indisponível em manutenção do Bacen |
| Dados | O nome pode vir truncado segundo regras do Bacen |
Segurança
A integração mexe com dinheiro de verdade e o Bearer token é a única chave: guarde e rotacione com cuidado, mascare nos logs, proteja o recebimento de callbacks por IP e valide a chave no DICT antes de pagar.
Tratamento de erros
Saiba quando repetir uma chamada e quando não: erro seu não se retenta, falha da instituição financeira ou da PayZu pede nova tentativa com espera crescente, e o timeout merece cuidado porque a operação pode ter valido.