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



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

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

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

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

O **TrueHolder** é uma trava de segurança que valida a &#x2A;*titularidade do documento (CPF ou CNPJ)** em transações. Aplica-se &#x2A;*tanto a cash-in (depósito) quanto a cash-out (saque)**, antes de aceitar o dinheiro entrando ou antes de enviar o dinheiro saindo, a PayZu compara o documento com o titular autorizado.

Se bate, a transação segue. Se não bate, é **bloqueada automaticamente**.

## Para que serve [#para-que-serve]

* **Anti-fraude em cash-in**: impede que terceiros paguem cobranças destinadas a um titular específico (lavagem, fraude de boleto-Pix, ataques de engenharia social).
* **Anti-fraude em cash-out**: impede saque para chave Pix de outro CPF/CNPJ, evitando desvio mesmo se o token vazar.
* **Conformidade KYC/AML**: garante que o fluxo financeiro respeite o titular declarado durante o onboarding.
* **Reduz disputas MED**: pagamentos que chegam do titular autorizado têm menos chance de virar contestação.

## Como funciona [#como-funciona]

<Mermaid
  chart="`
flowchart LR
  A[&#x22;Transação iniciada&#x22;] --> B{&#x22;TrueHolder<br>ativo?&#x22;}
  B -->|&#x22;Não&#x22;| C[&#x22;Processa normalmente&#x22;]
  B -->|&#x22;Sim&#x22;| D{&#x22;Documento bate<br>com o autorizado?&#x22;}
  D -->|&#x22;Sim&#x22;| C
  D -->|&#x22;Não&#x22;| E[&#x22;Bloqueia<br>status ERROR&#x22;]

  click E &#x22;#tratamento-de-bloqueio&#x22; &#x22;Como tratar bloqueio&#x22;

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

### Em cash-in (depósito) [#em-cash-in-depósito]

Quando você cria uma cobrança Pix via [`POST /pix`](/docs/pix-processamento/endpoints/pix-operations/post_pix) com `generatedDocument`, o TrueHolder valida que o **CPF/CNPJ do pagador** (`payerDocument`) bate com `generatedDocument` no momento do pagamento.

| Cenário                           | Resultado                                  |
| --------------------------------- | ------------------------------------------ |
| Pagador é o titular autorizado    | Transação `COMPLETED` normalmente          |
| Pagador é outra pessoa/empresa    | Pagamento **rejeitado**, transação `ERROR` |
| `generatedDocument` não informado | Sem validação, qualquer pagador é aceito   |

### Em cash-out (saque) [#em-cash-out-saque]

Em [`POST /withdraw`](/docs/pix-processamento/endpoints/withdrawals/post_withdraw) e [`POST /withdraw/qrcode`](/docs/pix-processamento/endpoints/withdrawals/post_withdraw_qrcode), o TrueHolder compara o **titular da chave Pix de destino** (consultado via DICT internamente) com o documento autorizado para a conta.

| Cenário                                  | Resultado                         |
| ---------------------------------------- | --------------------------------- |
| Chave Pix pertence ao titular autorizado | Saque `COMPLETED`                 |
| Chave Pix de outro CPF/CNPJ              | Saque **bloqueado** antes de sair |

## Como ativar [#como-ativar]

O TrueHolder **não é ligado por API**. Entre em contato com o **suporte da PayZu** para habilitar na sua conta. Uma vez ativo, funciona automaticamente em todas as transações.

## Tratamento de bloqueio [#tratamento-de-bloqueio]

Quando uma transação é bloqueada pelo TrueHolder, ela aparece no callback com:

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

Sugestões:

* **Avise o cliente final** que o pagamento veio de documento diferente do autorizado.
* **Logue o caso** com `id`, `payerDocument` e `generatedDocument`, pode ser sinal de tentativa de fraude ou erro de cadastro do cliente.
* **Não retente automaticamente**, o cliente precisa pagar do CPF/CNPJ correto.

## Combinação com outras travas [#combinação-com-outras-travas]

| Trava                                                        | Camada         | Cobre                                              |
| ------------------------------------------------------------ | -------------- | -------------------------------------------------- |
| **TrueHolder**                                               | Servidor PayZu | Bloqueia documento divergente em depósito/saque.   |
| [Consulta DICT](/docs/pix-processamento/best-practices/dict) | Aplicação      | Confirma titular antes de iniciar saque por chave. |
| [2FA](/docs/pix-processamento/two-factor)                    | Aplicação      | MFA antes de operações sensíveis.                  |
| IP whitelist do webhook                                      | Aplicação      | Aceita callbacks apenas do IP oficial PayZu.       |

Use **em conjunto**. TrueHolder é a última linha de defesa no servidor; DICT e 2FA são as primeiras camadas no seu app.

## Limitações [#limitações]

* TrueHolder valida **documento**, não nome ou banco. Cliente pode ter conta em vários bancos sob o mesmo CPF e qualquer uma é aceita.
* Em depósito, depende do `generatedDocument` ser informado na criação. Sem ele, não há comparação.
* Pessoa jurídica (CNPJ) com vários sócios pagando: bloqueado se for CPF de pessoa física, mesmo sócio. O documento autorizado é único.