TrueHolder

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 (withdrawal), 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 withdrawals to a Pix 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 (withdrawal)

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	Withdrawal `COMPLETED`
Pix key of another CPF/CNPJ	Withdrawal 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 a transaction is blocked by TrueHolder, it appears in the callback with:

{
  "id": "PAYZU20251123104518DF75D20A8F",
  "status": "ERROR",
  "type": "DEPOSIT",
  "cancellationReason": "TRUEHOLDER_DOCUMENT_MISMATCH",
  "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 key-based withdrawal.
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