Validating the key before you pay
Explains why to look up the key holder in DICT before sending a Pix.
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
Which route to use
Two routes query DICT: GET /pix/key and GET /user/dict. Both call the same service and share the same cache and the same per-account lookup quota: a call on one route consumes the other's quota and reuses its cached result. The difference is the token scope and the number of fields.
| Item | GET /pix/key | GET /user/dict |
|---|---|---|
| Parameter | pixKey | key |
| Token scope | DEPOSIT or WITHDRAW | WITHDRAW |
| Fields returned | 10, including branch, accountNumber, and institutionCode | 7 |
document | Raw digits | Formatted (000.000.000-00) |
Neither route hides a digit: the only difference is the CPF/CNPJ punctuation.
Only the WITHDRAW scope reaches both. To confirm the holder on screen before paying, GET /user/dict is enough and returns less sensitive data.
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
Lookup errors follow the standard API envelope; the Pix key/DICT specific codes, with what to do for each, are in Error codes.
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 | Per-account quota, shared by GET /pix/key and GET /user/dict |
| Cache | Response cached for up to 24h and reused by both routes |
| Availability | DICT may be unavailable during Bacen maintenance |
| Data | Names may come truncated according to Bacen rules |