Consulta DICT
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
| Código | Erro | Ação recomendada |
|---|---|---|
200 | Sucesso | Prosseguir com validação e pagamento |
400 | Chave inválida | Pedir correção ao usuário |
404 | Chave não existe | Informar que a chave não foi encontrada |
429 | Rate limit | Aguardar e tentar novamente |
500 | Erro interno | Retry com backoff exponencial |
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
Token Bearer é a única credencial da Magen. Trate como senha. Esta página cobre armazenamento, rotação, mascaramento em log, proteção do webhook por IP e validação DICT antes de pagar.
Tratamento de erros
4xx é erro seu (não retentar), 5xx é da Magen (retry com backoff), 429 é rate limit (aguardar) e timeout exige cuidado especial porque a operação pode ter sido aplicada. Esta página tem helper de retry e estratégia de logging.