TrueHolder

只有当 CPF 或 CNPJ 与授权持有人一致时才放行资金进出，任何第三方的收款或付款都会被自动拦截。

TrueHolder 是一种安全锁，用于在交易中验证文件（CPF 或 CNPJ）持有人身份。它同时适用于 cash-in（充值）和 cash-out（Pix 付款），在接收入账资金或发送出账资金前，PayZu 会将文件与授权持有人进行比对。

如果匹配，交易继续。如果不匹配，则自动被阻止。

用途

充值反欺诈：阻止第三方支付指定持有人的账单（洗钱、Pix 账单欺诈、社会工程攻击）。
Pix 付款反欺诈：阻止向其他 CPF/CNPJ 的 Pix 密钥付款，即使 token 泄露也能避免资金被转走。
KYC/AML 合规：确保资金流动遵循 onboarding 时声明的持有人。
减少 MED 争议：来自授权持有人的支付较少出现争议。

工作原理

在 cash-in（充值）中

当您通过 POST /pix 创建带 generatedDocument 的 Pix 账单时，TrueHolder 会在支付时验证付款人的 CPF/CNPJ（payerDocument）与 generatedDocument 是否匹配。

场景	结果
付款人是授权持有人	交易正常 `COMPLETED`
付款人是其他个人/企业	支付被拒绝，交易 `ERROR`
未提供 `generatedDocument`	不验证，任何付款人均被接受

在 cash-out（Pix 付款）中

在 POST /withdraw 和 POST /withdraw/qrcode 中，TrueHolder 会将目标 Pix 密钥持有人（通过内部 DICT 查询）与账户授权文件进行比对。

场景	结果
Pix 密钥属于授权持有人	Pix 付款 `COMPLETED`
Pix 密钥属于其他 CPF/CNPJ	Pix 付款在出账前被阻止

如何启用

TrueHolder 不通过 API 启用。请联系 PayZu 支持在您的账户上启用。一旦激活，将在所有交易中自动生效。

阻止处理

当 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（即便是股东本人）会被阻止。授权文件是唯一的。

TrueHolder

本页内容