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

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

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

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

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

**TrueHolder** is a security lock that validates &#x2A;*document ownership (CPF or CNPJ)** on transactions. It applies &#x2A;*to both cash-in (deposit) and cash-out (Pix payment)**, before accepting incoming money or before sending money out, PayZu compares the document with the authorized holder.

If it matches, the transaction proceeds. If it doesn't match, it is **blocked automatically**.

## What it's for [#what-its-for]

* **Anti-fraud in cash-in**: prevents third parties from paying charges intended for a specific holder (laundering, boleto-Pix fraud, social engineering attacks).
* **Anti-fraud in cash-out**: prevents Pix payments to a key of another CPF/CNPJ, avoiding diversion even if the token leaks.
* **KYC/AML compliance**: ensures the financial flow respects the holder declared during onboarding.
* **Reduces MED disputes**: payments arriving from the authorized holder are less likely to become contested.

## How it works [#how-it-works]

<Mermaid
  chart="`
flowchart LR
  A[&#x22;Transaction started&#x22;] --> B{&#x22;TrueHolder<br>active?&#x22;}
  B -->|&#x22;No&#x22;| C[&#x22;Process normally&#x22;]
  B -->|&#x22;Yes&#x22;| D{&#x22;Document matches<br>the authorized?&#x22;}
  D -->|&#x22;Yes&#x22;| C
  D -->|&#x22;No&#x22;| E[&#x22;Block<br>status ERROR&#x22;]

  click E &#x22;#tratamento-de-bloqueio&#x22; &#x22;How to handle a block&#x22;

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

### In cash-in (deposit) [#in-cash-in-deposit]

When you create a Pix charge via [`POST /pix`](/docs/pix-processamento/endpoints/pix-operations/post_pix) with `generatedDocument`, TrueHolder validates that the **payer's CPF/CNPJ** (`payerDocument`) matches `generatedDocument` at the moment of payment.

| Scenario                         | Result                                    |
| -------------------------------- | ----------------------------------------- |
| Payer is the authorized holder   | Transaction `COMPLETED` normally          |
| Payer is another person/company  | Payment **rejected**, transaction `ERROR` |
| `generatedDocument` not informed | No validation, any payer is accepted      |

### In cash-out (Pix payment) [#in-cash-out-pix-payment]

In [`POST /withdraw`](/docs/pix-processamento/endpoints/withdrawals/post_withdraw) and [`POST /withdraw/qrcode`](/docs/pix-processamento/endpoints/withdrawals/post_withdraw_qrcode), TrueHolder compares the **holder of the destination Pix key** (looked up via DICT internally) with the document authorized for the account.

| Scenario                                 | Result                                 |
| ---------------------------------------- | -------------------------------------- |
| Pix key belongs to the authorized holder | Pix payment `COMPLETED`                |
| Pix key of another CPF/CNPJ              | Pix payment **blocked** before leaving |

## How to activate [#how-to-activate]

TrueHolder **is not enabled via API**. Contact **PayZu support** to enable it on your account. Once active, it works automatically on all transactions.

## Handling a block [#handling-a-block]

When TrueHolder blocks a transaction, it arrives in the callback with `status` `ERROR` and both documents for you to compare. Do not rely on the `cancellationReason` text: it is free-form and may change.

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

Suggestions:

* **Notify the end customer** that the payment came from a different document than the authorized one.
* **Log the case** with `id`, `payerDocument` and `generatedDocument`, it may be a sign of fraud attempt or customer registration error.
* **Do not retry automatically**, the customer needs to pay from the correct CPF/CNPJ.

## Combination with other locks [#combination-with-other-locks]

| Lock                                                       | Layer        | Covers                                                     |
| ---------------------------------------------------------- | ------------ | ---------------------------------------------------------- |
| **TrueHolder**                                             | PayZu server | Blocks divergent document on deposit/withdrawal.           |
| [DICT Lookup](/docs/pix-processamento/best-practices/dict) | Application  | Confirms holder before initiating a key-based Pix payment. |
| [2FA](/docs/pix-processamento/two-factor)                  | Application  | MFA before sensitive operations.                           |
| Webhook IP whitelist                                       | Application  | Accepts callbacks only from the official PayZu IP.         |

Use them **together**. TrueHolder is the last line of defense on the server; DICT and 2FA are the first layers in your app.

## Limitations [#limitations]

* TrueHolder validates the **document**, not name or bank. The customer may have accounts at multiple banks under the same CPF and any of them is accepted.
* In deposits, it depends on `generatedDocument` being informed at creation. Without it, there is no comparison.
* Legal entity (CNPJ) with multiple partners paying: blocked if it is a CPF of an individual, even a partner. The authorized document is unique.