Account Controls (opt-in)
This page describes three optional, per-account controls that are OFF by default and that reinforce document (CPF/CNPJ) validation on PIX receipts and sends. They exist for specific compliance/anti-fraud scenarios.
Opt-in - no default impact
All controls on this page ship disabled by default. No existing integration is affected unless the account owner explicitly enables the control. While a control is disabled, the related request fields are accepted and stored but do not change processing. To enable a control or manage the authorized-CNPJ list, talk to your account team.
Overview
| Control | Direction | Related request field | Effect when enabled |
|---|---|---|---|
| Expected-payer verification | PIX-IN (charge) | expected_payer_document (cash-in) | An incoming PIX whose payer document does not match the expected one is rejected and returned to the payer |
| Block receiving from CNPJ | PIX-IN | - (no request field) | An incoming PIX from a CNPJ payer is rejected and returned to the payer |
| Block sending to CNPJ | PIX-OUT (send) | recipient_document (cash-out) | Sending to a CNPJ is blocked, except for CNPJs on the account's authorized list |
Expected-payer verification (PIX-IN)
Binds a charge to an expected payer through the optional expected_payer_document field on PIX Cash-In.
- Control enabled: an incoming PIX for that charge whose payer document does not match (or is missing) is rejected and returned to the payer (BACEN return), instead of being credited.
- Control disabled (default):
expected_payer_documentis merely stored and has no gating effect. - Field omitted: nothing changes.
Block receiving from CNPJ (PIX-IN)
Requires no new request field. When enabled, an incoming PIX whose payer is a CNPJ is rejected and returned to the payer instead of credited. When disabled (default), all receipts are processed normally.
Block sending to CNPJ (PIX-OUT)
Reinforces the optional recipient_document field on PIX Cash-Out by Key and PIX Cash-Out Copy and Paste.
When enabled on the paying account:
- The send must have a determinable recipient document. If the
pix_keyis itself a CPF/CNPJ, that key is authoritative. Otherwise (random/EVP key, phone, or email), you must sendrecipient_document. - No valid determinable recipient document → rejected with
cnpj_out_document_required. - Recipient CNPJ not on the account's authorized-CNPJ list → rejected with
cnpj_out_blocked. - A CPF recipient, or a CNPJ on the authorized list → allowed.
When disabled (default), recipient_document is ignored and nothing changes.
Authorized-CNPJ list
The authorized-CNPJ list is managed by your account team. Only CNPJs on that list can receive PIX when the "block sending to CNPJ" control is enabled.
Effect on the transaction lifecycle
When a receipt is blocked by one of these controls, it is rejected and returned to the payer (BACEN return) instead of credited. This is visible via the transaction status and the corresponding webhooks. See PIX Lifecycle and Query Cash-In by ID.
Error codes (PIX-OUT)
Code (errors[0].code) | HTTP | Meaning |
|---|---|---|
cnpj_out_document_required | 400/422 | Control enabled and no recipient document could be determined (random/EVP/phone/email key without recipient_document) |
cnpj_out_blocked | 400/422 | Control enabled and the recipient is a CNPJ that is not on the account's authorized-CNPJ list |