TrueHolder

Makes sure money only moves in or out when the CPF or CNPJ matches the authorized holder, and blocks any third-party activity on its own, both when receiving and when sending.

Security DICT Lookup 2FA MED

TrueHolder is a security lock that validates document ownership (CPF or CNPJ) on transactions. It applies 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

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

In cash-in (deposit)

When you create a Pix charge via 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 POST /withdraw and 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

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

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.

{
  "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

Lock	Layer	Covers
TrueHolder	PayZu server	Blocks divergent document on deposit/withdrawal.
DICT Lookup	Application	Confirms holder before initiating a key-based Pix payment.
2FA	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

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.

TrueHolder

On this page