最佳实践
说明为什么在发起 Pix 之前要到 DICT 查询密钥持有人。
什么是 DICT
DICT（交易账户标识符目录） 是由巴西中央银行维护的中央数据库， 保存巴西所有已注册的 Pix 密钥。通过它，您可以验证密钥是否存在， 并在发起支付前获取收款人的信息。
为什么要在支付前查询 DICT？
- 确认密钥存在 并处于激活状态，避免向无效或不存在的密钥支付。
- 验证持有人 是否为用户所指定的收款人，作为反欺诈环节。
- 显示收款人姓名 以供确认后再完成交易（提升 UX）。
- 降低运营成本，避免发起注定会失败的支付尝试。
推荐流程
该用哪个端点
有两个端点可以查询 DICT：GET /pix/key 和 GET /user/dict。两者调用同一个服务，共用同一份缓存和同一个按账户计的查询配额：在一个端点上发起的调用会消耗另一个端点的配额，也会复用已缓存的结果。区别在于令牌权限和返回字段数量。
| 项目 | GET /pix/key | GET /user/dict |
|---|---|---|
| 参数 | pixKey | key |
| 令牌权限 | DEPOSIT 或 WITHDRAW | WITHDRAW |
| 返回字段 | 10 个，含 branch、accountNumber、institutionCode | 7 个 |
document | 原始数字 | 已格式化（000.000.000-00） |
两条路由都不会隐藏任何数字，区别仅在于 CPF/CNPJ 的标点。
只有 WITHDRAW 权限同时覆盖两者。若只是在付款前于界面上确认持有人，用 GET /user/dict 即可，返回的敏感数据更少。
何时查询
在以下情况下，DICT 查询是 必须的：
- 通过 Pix 密钥发起支付（
POST /withdraw）。 - 首次向新收款人转账。
- 大额支付。
- 偏离用户常规模式的交易。
在某些情况下，查询可以是 可选的：
- 向同一收款人发起的周期性支付，且数据已经过验证。
- 技术故障后立即重试。
在这些场景中，可在有限时间内使用缓存数据。
错误处理
查询错误遵循 API 的标准信封格式；Pix 密钥/DICT 相关的错误代码及各自的处理方式见错误代码。
安全性
DICT 确认密钥存在，但 并不能保证 支付是合法的。 请始终结合其他反欺诈校验一起使用。
向用户展示收款人信息时，请 遮掩 敏感数据，如 CPF 和 CNPJ：
- CPF：
123.***.***-01 - CNPJ：
12.345.***/**01-00
为每个用户实施 rate limiting 来限制 DICT 查询频率，并监控异常的 高频查询，这可能是密钥枚举攻击的迹象。 DICT 返回的数据仅供即时验证使用，不应在没有必要的情况下持久化存储。
限制和注意事项
| 项目 | 信息 |
|---|---|
| Rate limit | 按账户计的配额，GET /pix/key 与 GET /user/dict 共用 |
| 缓存 | 响应最长缓存 24 小时，两个端点共同复用 |
| 可用性 | DICT 在 Bacen 维护期间可能不可用 |
| 数据 | 姓名可能根据 Bacen 规则被截断显示 |