Best Practices - DICT Lookup

What is DICT?

DICT (Directory of Transactional Account Identifiers) is the central database maintained by the Brazilian Central Bank that stores all registered Pix keys in Brazil. Through it, you can validate the existence of a key and retrieve recipient information before making a payment, ensuring that the money will be sent to the correct person or company.

---

Why query DICT before paying?

Querying DICT beforehand brings several benefits to your operation. It confirms that the Pix key exists and is active, avoiding payments to invalid or non-existent keys. It also allows you to validate whether the holder is who they claim to be, acting as an anti-fraud layer. From a user experience perspective, it enables displaying the recipient's name for confirmation before completing the transaction. Finally, it reduces operational costs by avoiding payment attempts that would fail anyway.

---

Recommended Flow

The ideal flow for Pix key payments follows this sequence:

User provides the Pix key
            ↓
Query DICT (GET /pix/key)
            ↓
Validate response and display data to user
            ↓
User confirms the recipient
            ↓
Execute payment (POST /withdraw)

---

When to Query

DICT lookup should be performed mandatorily before Pix key payments (POST /withdraw), on the first payment to a new recipient, for high-value payments, and for transactions that deviate from the user's usual pattern.

In some scenarios the lookup may be optional, such as recurring payments to the same recipient where data has already been validated, or immediate retry after a technical failure. In these cases, it is acceptable to use cached data for a limited period.

---

Error Handling

---

Security Best Practices

DICT confirms that a key exists, but this does not guarantee that the payment is legitimate. Always combine the lookup with other anti-fraud validations in your application.

When displaying recipient data to the user, mask sensitive information such as CPF and CNPJ. The document should appear partially hidden, for example 123.***.***-01 for CPF or 12.345.***/**01-00 for CNPJ.

Implement rate limiting per user on DICT queries and monitor excessive lookups, as they may indicate key enumeration attempts. Data returned by DICT is for momentary validation and should not be persisted without necessity.

---

Limits and Considerations