# TrueHolder (/zh/docs/pix-processamento/trueholder)

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/best-practices/security" title="安全" />

  <QuickLink href="/docs/pix-processamento/best-practices/dict" title="DICT 查询" />

  <QuickLink href="/docs/pix-processamento/two-factor" title="2FA" />

  <QuickLink href="/docs/pix-processamento/med" title="MED" />
</QuickLinks>

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

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

## 用途 [#用途]

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

## 工作原理 [#工作原理]

<Mermaid
  chart="`
flowchart LR
  A[&#x22;交易发起&#x22;] --> B{&#x22;TrueHolder<br>已启用？&#x22;}
  B -->|&#x22;否&#x22;| C[&#x22;正常处理&#x22;]
  B -->|&#x22;是&#x22;| D{&#x22;文件与授权<br>持有人匹配？&#x22;}
  D -->|&#x22;是&#x22;| C
  D -->|&#x22;否&#x22;| E[&#x22;阻止<br>状态 ERROR&#x22;]

  click E &#x22;#tratamento-de-bloqueio&#x22; &#x22;如何处理阻止&#x22;

  style C fill:#14ce71,stroke:#0eb464,color:#ffffff
  style E fill:#ef4444,stroke:#dc2626,color:#ffffff
`"
/>

### 在 cash-in（充值）中 [#在-cash-in充值中]

当您通过 [`POST /pix`](/docs/pix-processamento/endpoints/pix-operations/post_pix) 创建带 `generatedDocument` 的 Pix 账单时，TrueHolder 会在支付时验证**付款人的 CPF/CNPJ**（`payerDocument`）与 `generatedDocument` 是否匹配。

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

### 在 cash-out（Pix 付款）中 [#在-cash-outpix-付款中]

在 [`POST /withdraw`](/docs/pix-processamento/endpoints/withdrawals/post_withdraw) 和 [`POST /withdraw/qrcode`](/docs/pix-processamento/endpoints/withdrawals/post_withdraw_qrcode) 中，TrueHolder 会将**目标 Pix 密钥持有人**（通过内部 DICT 查询）与账户授权文件进行比对。

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

## 如何启用 [#如何启用]

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

## 阻止处理 [#阻止处理]

当 TrueHolder 拦截交易时,回调中会带上 `status` `ERROR` 和两个证件号供你比对。请勿依赖 `cancellationReason` 的文本:该字段为自由文本,可能变更。

```json
{
  "id": "PAYZU20260811K7M2X9QP4T000000",
  "status": "ERROR",
  "type": "DEPOSIT",
  "cancellationReason": null,
  "payerDocument": "11122233344",
  "generatedDocument": "55566677788"
}
```

建议：

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

## 与其他安全锁的组合 [#与其他安全锁的组合]

| 安全锁                                                    | 层级        | 覆盖范围                          |
| ------------------------------------------------------ | --------- | ----------------------------- |
| **TrueHolder**                                         | PayZu 服务器 | 阻止充值/Pix 付款中文件不一致的情况。         |
| [DICT 查询](/docs/pix-processamento/best-practices/dict) | 应用层       | 在通过密钥发起 Pix 付款前确认持有人。         |
| [2FA](/docs/pix-processamento/two-factor)              | 应用层       | 敏感操作前进行 MFA。                  |
| webhook IP 白名单                                         | 应用层       | 仅接受来自 PayZu 官方 IP 的 callback。 |

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

## 限制 [#限制]

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