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

::: tip 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](/pix-cashin#request-body).

- **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](/pix-cashout-key#request-body) e no [PIX Cash-Out Copia e Cola](/pix-cashout-emv#request-body).

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](/pix-lifecycle) e [Consultar Cash-In por ID](/pix-cashin-status).

## 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 |