TrueHolder
Makes sure a Pix charge is only paid by the CPF or CNPJ informed at creation, and refuses payments made by third parties on its own.
TrueHolder is a security lock that validates the payer's document ownership (CPF or CNPJ) on Pix charges (cash-in): before accepting incoming money, the document of whoever pays is compared with the document informed in the charge.
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).
- 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)
TrueHolder does not apply to POST /withdraw or POST /withdraw/qrcode: the API does not block Pix payments to a key of another CPF/CNPJ. To check the key holder before paying, use the DICT Lookup. To protect the withdrawal token, register the source IPs in the IP whitelist.
How to activate
TrueHolder is not enabled via API. Contact PayZu support to enable it on your account. Once active, it works automatically on every charge created with generatedDocument.
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,payerDocumentandgeneratedDocument, 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 | Refuses payment from a divergent document on a Pix charge. |
| 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
generatedDocumentbeing 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.