Contrôles de compte (opt-in)

Cette page décrit trois contrôles optionnels, par compte, désactivés par défaut qui renforcent la validation des documents (CPF/CNPJ) sur les réceptions et les envois PIX. Ils existent pour des scénarios de compliance/anti-fraude spécifiques.

Opt-in - aucun impact par défaut

Tous les contrôles de cette page sont désactivés par défaut. Aucune intégration existante n'est affectée à moins que le titulaire du compte n'active explicitement le contrôle. Tant qu'un contrôle est désactivé, les champs de request associés sont acceptés et stockés, mais ne modifient pas le traitement. Pour activer un contrôle ou gérer la liste des CNPJ autorisés, contactez l'équipe de votre compte.

Vue d'ensemble

Contrôle	Direction	Champ de request associé	Effet lorsqu'activé
Vérification du payeur attendu	PIX-IN (facturation)	expected_payer_document (cash-in)	Un PIX reçu dont le document du payeur ne correspond pas à celui attendu est rejeté et renvoyé au payeur
Bloquer la réception depuis un CNPJ	PIX-IN	- (pas de champ de request)	Un PIX reçu d'un payeur CNPJ est rejeté et renvoyé au payeur
Bloquer l'envoi vers un CNPJ	PIX-OUT (envoi)	recipient_document (cash-out)	L'envoi vers un CNPJ est bloqué, sauf pour les CNPJ figurant sur la liste autorisée du compte

Vérification du payeur attendu (PIX-IN)

Lie une facturation à un payeur attendu via le champ optionnel expected_payer_document dans PIX Cash-In.

• Contrôle activé : un PIX reçu pour cette facturation dont le document du payeur ne correspond pas (ou est absent) est rejeté et renvoyé au payeur (BACEN/devolução), au lieu d'être crédité.
• Contrôle désactivé (par défaut) : le expected_payer_document est simplement stocké et n'a aucun effet de blocage.
• Champ omis : rien ne change.

Bloquer la réception depuis un CNPJ (PIX-IN)

Ne requiert aucun nouveau champ de request. Lorsqu'il est activé, un PIX reçu dont le payeur est un CNPJ est rejeté et renvoyé au payeur au lieu d'être crédité. Lorsqu'il est désactivé (par défaut), toutes les réceptions sont traitées normalement.

Bloquer l'envoi vers un CNPJ (PIX-OUT)

Renforce le champ optionnel recipient_document dans PIX Cash-Out par clé et PIX Cash-Out Copier-Coller.

Lorsqu'il est activé sur le compte payeur :

• L'envoi doit avoir un document de destinataire déterminable. Si la pix_key est déjà un CPF/CNPJ, cette clé fait autorité. Sinon (clé aléatoire/EVP, téléphone ou email), vous devez envoyer recipient_document.
• Sans document de destinataire valide déterminable → rejet avec cnpj_out_document_required.
• Destinataire CNPJ absent de la liste des CNPJ autorisés du compte → rejet avec cnpj_out_blocked.
• Destinataire CPF, ou CNPJ présent sur la liste autorisée → autorisé.

Lorsqu'il est désactivé (par défaut), recipient_document est ignoré et rien ne change.

Liste des CNPJ autorisés

La liste des CNPJ autorisés est gérée par l'équipe de votre compte. Seuls les CNPJ présents sur cette liste peuvent recevoir un PIX lorsque le contrôle « bloquer l'envoi vers un CNPJ » est activé.

Effet sur le cycle de vie de la transaction

Lorsqu'une réception est bloquée par l'un de ces contrôles, elle est rejetée et renvoyée au payeur (devolução BACEN) au lieu d'être créditée. Cela est visible via le status de la transaction et les webhooks correspondants. Voir PIX Lifecycle et Consulter Cash-In par ID.

Codes d'erreur (PIX-OUT)

Code (errors[0].code)	HTTP	Signification
cnpj_out_document_required	400/422	Contrôle activé et aucun document du destinataire n'a pu être déterminé (clé aléatoire/EVP/téléphone/email sans recipient_document)
cnpj_out_blocked	400/422	Contrôle activé et le destinataire est un CNPJ qui ne figure pas sur la liste des CNPJ autorisés du compte