TrueHolder

安全 DICT 查询 2FA MED

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

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

用途

充值反欺诈：阻止第三方支付指定持有人的账单（洗钱、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（提现）中

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

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

如何启用

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

阻止处理

当交易被 TrueHolder 阻止时，会在 callback 中显示为：

{
  "id": "SAQ20251123104518DF75D20A8F",
  "status": "ERROR",
  "type": "DEPOSIT",
  "cancellationReason": "TRUEHOLDER_DOCUMENT_MISMATCH",
  "payerDocument": "11122233344",
  "generatedDocument": "55566677788"
}

建议：

告知终端客户支付来自与授权不同的文件。
记录该案例（包含 id、payerDocument 和 generatedDocument），可能是欺诈尝试或客户注册错误的信号。
不要自动重试，客户需要使用正确的 CPF/CNPJ 支付。

与其他安全锁的组合

安全锁	层级	覆盖范围
TrueHolder	Saq 服务器	阻止充值/提现中文件不一致的情况。
DICT 查询	应用层	在通过密钥发起提现前确认持有人。
2FA	应用层	敏感操作前进行 MFA。
webhook IP 白名单	应用层	仅接受来自 Saq 官方 IP 的 callback。

请配合使用。TrueHolder 是服务器端的最后一道防线；DICT 和 2FA 是您应用中的第一道防线。

限制

TrueHolder 验证的是文件，而非姓名或银行。客户可以在多家银行拥有同一 CPF 名下的账户，任何一家都被接受。
在充值中，依赖于创建时提供的 generatedDocument。未提供则不进行比对。
法人（CNPJ）有多个股东支付时：如果是自然人 CPF（即便是股东本人）会被阻止。授权文件是唯一的。

TrueHolder

On this page