Controles de Cuenta (opt-in)
Esta pagina describe tres controles opcionales, por cuenta, desactivados por default que refuerzan la validacion de documentos (CPF/CNPJ) en recepciones y envios PIX. Existen para escenarios especificos de compliance/antifraude.
Opt-in - ningun impacto por default
Todos los controles de esta pagina vienen desactivados por default. Ninguna integracion existente es afectada a menos que el titular de la cuenta active explicitamente el control. Mientras un control este desactivado, los campos de request relacionados son aceptados y almacenados, pero no alteran el procesamiento. Para activar un control o gestionar la lista de CNPJs autorizados, hable con el equipo de su cuenta.
Vision general
| Control | Direccion | Campo de request relacionado | Efecto cuando activado |
|---|---|---|---|
| Verificacion de pagador esperado | PIX-IN (cobro) | expected_payer_document (cash-in) | PIX recibido cuyo documento del pagador no corresponde al esperado es rechazado y devuelto al pagador |
| Bloquear recepcion de CNPJ | PIX-IN | - (sin campo de request) | PIX recibido de un pagador CNPJ es rechazado y devuelto al pagador |
| Bloquear envio a CNPJ | PIX-OUT (envio) | recipient_document (cash-out) | Envio a CNPJ es bloqueado, excepto para CNPJs en la lista autorizada de la cuenta |
Verificacion de pagador esperado (PIX-IN)
Vincula un cobro a un pagador esperado mediante el campo opcional expected_payer_document en PIX Cash-In.
- Control activado: un PIX recibido para ese cobro cuyo documento del pagador no corresponda (o este ausente) es rechazado y devuelto al pagador (BACEN/devolucion), en vez de acreditado.
- Control desactivado (default): el
expected_payer_documentes solo almacenado y no tiene efecto de bloqueo. - Campo omitido: nada cambia.
Bloquear recepcion de CNPJ (PIX-IN)
No requiere ningun campo nuevo de request. Cuando activado, un PIX recibido cuyo pagador sea un CNPJ es rechazado y devuelto al pagador en vez de acreditado. Cuando desactivado (default), todas las recepciones son procesadas normalmente.
Bloquear envio a CNPJ (PIX-OUT)
Refuerza el campo opcional recipient_document en PIX Cash-Out por Clave y en PIX Cash-Out Copia y Pega.
Cuando activado en la cuenta pagadora:
- El envio necesita tener un documento de destinatario determinable. Si la
pix_keyya es un CPF/CNPJ, esa clave es autoritativa. En caso contrario (clave aleatoria/EVP, telefono o e-mail), usted debe enviarrecipient_document. - Sin documento valido de destinatario determinable → rechazo con
cnpj_out_document_required. - Destinatario CNPJ fuera de la lista de CNPJs autorizados de la cuenta → rechazo con
cnpj_out_blocked. - Destinatario CPF, o CNPJ presente en la lista autorizada → permitido.
Cuando desactivado (default), recipient_document es ignorado y nada cambia.
Lista de CNPJs autorizados
La lista de CNPJs autorizados es gestionada por el equipo de su cuenta. Solo CNPJs presentes en esa lista pueden recibir PIX cuando el control "bloquear envio a CNPJ" esta activado.
Efecto en el ciclo de vida de la transaccion
Cuando una recepcion es bloqueada por uno de estos controles, ella es rechazada y devuelta al pagador (devolucion BACEN) en vez de acreditada. Esto es visible por el status de la transaccion y por los webhooks correspondientes. Vea PIX Lifecycle y Consultar Cash-In por ID.
Codigos de error (PIX-OUT)
Codigo (errors[0].code) | HTTP | Significado |
|---|---|---|
cnpj_out_document_required | 400/422 | Control activado y ningun documento del destinatario pudo ser determinado (clave aleatoria/EVP/telefono/e-mail sin recipient_document) |
cnpj_out_blocked | 400/422 | Control activado y el destinatario es un CNPJ que no esta en la lista de CNPJs autorizados de la cuenta |