Controles de Conta (opt-in)

Esta página descreve três controles opcionais, por conta, desativados por padrão que reforçam a validação de documentos (CPF/CNPJ) em recebimentos e envios PIX. Eles existem para cenários de compliance/antifraude específicos.

Opt-in - nenhum impacto por padrão

Todos os controles desta página vêm desativados por padrão. Nenhuma integração existente é afetada a menos que o titular da conta ative explicitamente o controle. Enquanto um controle estiver desativado, os campos de request relacionados são aceitos e armazenados, mas não alteram o processamento. Para ativar um controle ou gerir a lista de CNPJs autorizados, fale com o time da sua conta.

Visão geral

Controle	Direção	Campo de request relacionado	Efeito quando ativado
Verificação de pagador esperado	PIX-IN (cobrança)	expected_payer_document (cash-in)	PIX recebido cujo documento do pagador não corresponde ao esperado é rejeitado e devolvido ao pagador
Bloquear recebimento de CNPJ	PIX-IN	- (sem campo de request)	PIX recebido de um pagador CNPJ é rejeitado e devolvido ao pagador
Bloquear envio para CNPJ	PIX-OUT (envio)	recipient_document (cash-out)	Envio para CNPJ é bloqueado, exceto para CNPJs na lista autorizada da conta

Verificação de pagador esperado (PIX-IN)

Vincula uma cobrança a um pagador esperado por meio do campo opcional expected_payer_document no PIX Cash-In.

• Controle ativado: um PIX recebido para essa cobrança cujo documento do pagador não corresponda (ou esteja ausente) é rejeitado e devolvido ao pagador (BACEN/devolução), em vez de creditado.
• Controle desativado (padrão): o expected_payer_document é apenas armazenado e não tem efeito de bloqueio.
• Campo omitido: nada muda.

Bloquear recebimento de CNPJ (PIX-IN)

Não requer nenhum campo novo de request. Quando ativado, um PIX recebido cujo pagador seja um CNPJ é rejeitado e devolvido ao pagador em vez de creditado. Quando desativado (padrão), todos os recebimentos são processados normalmente.

Bloquear envio para CNPJ (PIX-OUT)

Reforça o campo opcional recipient_document no PIX Cash-Out por Chave e no PIX Cash-Out Copia e Cola.

Quando ativado na conta pagadora:

• O envio precisa ter um documento de destinatário determinável. Se a pix_key já é um CPF/CNPJ, essa chave é autoritativa. Caso contrário (chave aleatória/EVP, telefone ou e-mail), você deve enviar recipient_document.
• Sem documento válido de destinatário determinável → rejeição com cnpj_out_document_required.
• Destinatário CNPJ fora da lista de CNPJs autorizados da conta → rejeição com cnpj_out_blocked.
• Destinatário CPF, ou CNPJ presente na lista autorizada → permitido.

Quando desativado (padrão), recipient_document é ignorado e nada muda.

Lista de CNPJs autorizados

A lista de CNPJs autorizados é gerida pelo time da sua conta. Somente CNPJs presentes nessa lista podem receber PIX quando o controle "bloquear envio para CNPJ" está ativado.

Efeito no ciclo de vida da transação

Quando um recebimento é bloqueado por um destes controles, ele é rejeitado e devolvido ao pagador (devolução BACEN) em vez de creditado. Isso é visível pelo status da transação e pelos webhooks correspondentes. Veja PIX Lifecycle e Consultar Cash-In por ID.

Códigos de erro (PIX-OUT)

Código (errors[0].code)	HTTP	Significado
cnpj_out_document_required	400/422	Controle ativado e nenhum documento do destinatário pôde ser determinado (chave aleatória/EVP/telefone/e-mail sem recipient_document)
cnpj_out_blocked	400/422	Controle ativado e o destinatário é um CNPJ que não está na lista de CNPJs autorizados da conta