TrueHolder

Garante que o dinheiro só entra ou sai quando o CPF ou CNPJ bate com o titular autorizado, e bloqueia sozinho qualquer movimentação de terceiros, tanto no recebimento quanto no envio.

Segurança Consulta DICT 2FA MED

O TrueHolder é uma trava de segurança que valida a titularidade do documento (CPF ou CNPJ) em transações. Aplica-se tanto a cash-in (depósito) quanto a cash-out (pagamento Pix), 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

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 pagamento Pix para chave 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

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)

Em POST /withdraw e 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	Pagamento Pix `COMPLETED`
Chave Pix de outro CPF/CNPJ	Pagamento Pix bloqueado antes de sair

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

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	Bloqueia documento divergente em depósito/pagamento 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