DICT Lookup
What is DICT
The DICT (Transactional Account Identifiers Directory) is the central database maintained by the Brazilian Central Bank that holds every Pix key registered in Brazil. Through it, you validate that a key exists and retrieve the recipient's data before making a payment.
Why look up DICT before paying?
- Confirms the key exists and is active, preventing payments to invalid or non-existent keys.
- Validates the account holder that the user claimed as the recipient, acting as an anti-fraud layer.
- Shows the recipient's name for confirmation before completing the transaction (better UX).
- Reduces operational costs by avoiding payment attempts that would fail.
Recommended flow
When to query
The DICT lookup is mandatory before:
- Payments via Pix key (
POST /withdraw). - First transfer to a new recipient.
- High-value payments.
- Transactions outside the user's usual pattern.
In some cases the lookup may be optional:
- Recurring payments to the same recipient whose data has already been validated.
- Immediate retry after a technical failure.
In those cases, it is acceptable to use cached data for a limited period.
Error handling
| Code | Error | Recommended action |
|---|---|---|
200 | Success | Proceed with validation and payment |
400 | Invalid key | Ask the user to correct it |
404 | Key does not exist | Inform that the key was not found |
429 | Rate limit | Wait and try again |
500 | Internal error | Retry with exponential backoff |
Security
DICT confirms that the key exists, but this does not guarantee that the payment is legitimate. Always combine the lookup with other anti-fraud validations.
When showing the recipient's data to the user, mask sensitive data such as CPF and CNPJ:
- CPF:
123.***.***-01 - CNPJ:
12.345.***/**01-00
Implement rate limiting per user on DICT lookups and monitor excessive searches, which may indicate key enumeration attempts. The data returned by DICT is for momentary validation and should not be persisted without need.
Limits and considerations
| Item | Information |
|---|---|
| Rate limit | Check the limits for your account |
| Cache | Data may be cached for up to 24h |
| Availability | DICT may be unavailable during Bacen maintenance |
| Data | Names may come truncated according to Bacen rules |
Segurança
Token Bearer é a única credencial da Saq. 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 Saq (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.