TrueHolder
确保 Pix 账单只能由创建时填写的 CPF 或 CNPJ 支付，第三方的付款会被自动拒绝。
TrueHolder 是一种安全锁，用于在 Pix 账单（cash-in） 中验证付款人的文件（CPF 或 CNPJ）持有人身份：在接收入账资金前，会将付款人的文件与账单中填写的文件进行比对。
如果匹配，交易继续。如果不匹配，则自动被阻止。
用途
- 充值反欺诈：阻止第三方支付指定持有人的账单（洗钱、Pix 账单欺诈、社会工程攻击）。
- KYC/AML 合规：确保资金流动遵循 onboarding 时声明的持有人。
- 减少 MED 争议：来自授权持有人的支付较少出现争议。
工作原理
在 cash-in（充值）中
当您通过 POST /pix 创建带 generatedDocument 的 Pix 账单时，TrueHolder 会在支付时验证付款人的 CPF/CNPJ（payerDocument）与 generatedDocument 是否匹配。
| 场景 | 结果 |
|---|---|
| 付款人是授权持有人 | 交易正常 COMPLETED |
| 付款人是其他个人/企业 | 支付被拒绝，交易 ERROR |
未提供 generatedDocument | 不验证，任何付款人均被接受 |
在 cash-out（Pix 付款）中
TrueHolder 不适用于 POST /withdraw 和 POST /withdraw/qrcode：API 不会拦截向其他 CPF/CNPJ 的 Pix 密钥付款。如需在付款前确认密钥持有人，请使用 DICT 查询。如需保护提现 token，请在 IP 白名单中登记来源 IP。
如何启用
TrueHolder 不通过 API 启用。请联系 PayZu 支持在您的账户上启用。一旦激活，将在所有带 generatedDocument 创建的账单中自动生效。
阻止处理
当 TrueHolder 拦截交易时,回调中会带上 status ERROR 和两个证件号供你比对。请勿依赖 cancellationReason 的文本:该字段为自由文本,可能变更。
{
"id": "PAYZU20260811K7M2X9QP4T000000",
"status": "ERROR",
"type": "DEPOSIT",
"cancellationReason": null,
"payerDocument": "11122233344",
"generatedDocument": "55566677788"
}建议：
- 告知终端客户支付来自与授权不同的文件。
- 记录该案例（包含
id、payerDocument和generatedDocument），可能是欺诈尝试或客户注册错误的信号。 - 不要自动重试，客户需要使用正确的 CPF/CNPJ 支付。
与其他安全锁的组合
| 安全锁 | 层级 | 覆盖范围 |
|---|---|---|
| TrueHolder | PayZu 服务器 | 拒绝 Pix 账单中文件不一致的付款。 |
| DICT 查询 | 应用层 | 在通过密钥发起 Pix 付款前确认持有人。 |
| 2FA | 应用层 | 敏感操作前进行 MFA。 |
| webhook IP 白名单 | 应用层 | 仅接受来自 PayZu 官方 IP 的 callback。 |
请配合使用。TrueHolder 是服务器端的最后一道防线；DICT 和 2FA 是您应用中的第一道防线。
限制
- TrueHolder 验证的是文件，而非姓名或银行。客户可以在多家银行拥有同一 CPF 名下的账户，任何一家都被接受。
- 在充值中，依赖于创建时提供的
generatedDocument。未提供则不进行比对。 - 法人（CNPJ）有多个股东支付时：如果是自然人 CPF（即便是股东本人）会被阻止。授权文件是唯一的。