DICT 查询
什么是 DICT
DICT（交易账户标识符目录） 是由巴西中央银行维护的中央数据库， 保存巴西所有已注册的 Pix 密钥。通过它，您可以验证密钥是否存在， 并在发起支付前获取收款人的信息。
为什么要在支付前查询 DICT？
- 确认密钥存在 并处于激活状态，避免向无效或不存在的密钥支付。
- 验证持有人 是否为用户所指定的收款人，作为反欺诈环节。
- 显示收款人姓名 以供确认后再完成交易（提升 UX）。
- 降低运营成本，避免发起注定会失败的支付尝试。
推荐流程
何时查询
在以下情况下，DICT 查询是 必须的：
- 通过 Pix 密钥发起支付（
POST /withdraw）。 - 首次向新收款人转账。
- 大额支付。
- 偏离用户常规模式的交易。
在某些情况下，查询可以是 可选的：
- 向同一收款人发起的周期性支付，且数据已经过验证。
- 技术故障后立即重试。
在这些场景中，可在有限时间内使用缓存数据。
错误处理
| 代码 | 错误 | 推荐操作 |
|---|---|---|
200 | 成功 | 继续验证并发起支付 |
400 | 密钥无效 | 请求用户修正 |
404 | 密钥不存在 | 告知未找到该密钥 |
429 | Rate limit | 等待后重试 |
500 | 内部错误 | 使用指数退避策略重试 |
安全性
DICT 确认密钥存在，但 并不能保证 支付是合法的。 请始终结合其他反欺诈校验一起使用。
向用户展示收款人信息时，请 遮掩 敏感数据，如 CPF 和 CNPJ：
- CPF：
123.***.***-01 - CNPJ：
12.345.***/**01-00
为每个用户实施 rate limiting 来限制 DICT 查询频率，并监控异常的 高频查询，这可能是密钥枚举攻击的迹象。 DICT 返回的数据仅供即时验证使用，不应在没有必要的情况下持久化存储。
限制和注意事项
| 项目 | 信息 |
|---|---|
| Rate limit | 请查询您账户的相应限制 |
| 缓存 | 数据最长可缓存 24 小时 |
| 可用性 | DICT 在 Bacen 维护期间可能不可用 |
| 数据 | 姓名可能根据 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.