TrueHolder

Garante que a cobrança Pix só é paga pelo CPF ou CNPJ informado na criação e recusa sozinha o pagamento feito por terceiros.

Segurança Consulta DICT 2FA MED

O TrueHolder é uma trava de segurança que valida a titularidade do documento (CPF ou CNPJ) do pagador em cobranças Pix (cash-in): antes de aceitar o dinheiro entrando, o documento de quem paga é comparado com o documento informado na cobrança.

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

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).
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

Em cash-in (depósito)

Quando você cria uma cobrança Pix via 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 (pagamento Pix)

O TrueHolder não se aplica a POST /withdraw nem a POST /withdraw/qrcode: a API não bloqueia pagamento Pix para chave de outro CPF/CNPJ. Para conferir o titular da chave antes de pagar, use a Consulta DICT. Para proteger o token de saque, cadastre os IPs de origem na whitelist de IP.

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 toda cobrança criada com generatedDocument.

Tratamento de bloqueio

Quando uma transação é bloqueada pelo TrueHolder, ela chega no callback com status ERROR e os dois documentos para você comparar. Não dependa do texto de cancellationReason: ele é livre e pode mudar.

{
  "id": "PAYZU20260811K7M2X9QP4T000000",
  "status": "ERROR",
  "type": "DEPOSIT",
  "cancellationReason": null,
  "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

Trava	Camada	Cobre
TrueHolder	Servidor PayZu	Recusa pagamento de documento divergente em cobrança Pix.
Consulta DICT	Aplicação	Confirma titular antes de iniciar pagamento Pix por chave.
2FA	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

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.

TrueHolder

Nesta página