Pix en profondeur : intégrer et exploiter. 7 chapitres et un QCM final.

Chapitre 1. Le DICT n'est pas un annuaire : c'est un quota.

Le DICT, Diretório de Identificadores de Contas Transacionais, traduit une chave Pix en coordonnées de compte. L'intégration qui casse en production ne casse presque jamais sur cette traduction, mais sur le rationnement. Le Banco Central do Brasil compte les consultations, utilisateur par utilisateur et participant par participant, et refuse le service quand le compteur tombe à zéro. Une équipe qui ignore ce mécanisme jusqu'à la mise en production l'apprend par un pic d'erreurs HTTP 429.

Ce que le DICT accepte de stocker, et en quelle quantité

• Cinq chaves par conta transacional pour un titulaire inscrit au CPF, vingt pour un titulaire inscrit au CNPJ. Le plafond porte sur le compte, quel que soit le nombre de cotitulaires (Manual Operacional do DICT, version 8.4, Banco Central do Brasil).
• Une chave, un compte. Le même identifiant ne peut jamais pointer deux comptes transactionnels à la fois.
• La chave aleatória est produite par le DICT, pas choisie par l'utilisateur : c'est un UUID au format de la RFC 4122. Aucune personnalisation n'est possible.
• Formats de stockage : CPF sur 11 chiffres, CNPJ sur 14 caractères alphanumériques, tous deux sans point ni tiret ; téléphone au standard E.164 ; adresse électronique sur 77 caractères au plus.
• Le nom affiché au payeur vient de la Receita Federal. Pour une personne morale, le champ Name porte la razão social et le champ TradeName le nome fantasia, seulement s'il figure à l'inscription au CNPJ. Pour un microempreendedor individual, TradeName doit rester vide.

Chaque consultation transporte l'en-tête PI-PayerId. Il porte le CPF ou le CNPJ de l'utilisateur qui paiera, au format numérique nu, et doit rester identique pour toutes les consultations de cet utilisateur chez un participant donné. Le DICT s'en sert pour tenir deux indicateurs : les consultations qui n'ont produit aucun ordre de paiement, et les consultations portant sur des chaves non enregistrées. Le second coûte vingt fois le premier.

Chapitre 2. Perdre une chave : portabilité, revendication, blocage.

Deux procédures déplacent une chave d'un établissement à un autre. La portabilidade vise le titulaire qui change de PSP en gardant sa chave. La reivindicação de posse vise un tiers qui affirme être le vrai détenteur de l'identifiant, un numéro de téléphone recyclé ou une adresse électronique reprise. Elles se ressemblent. Leur comportement par défaut est pourtant inverse, et c'est là que se perd une chave d'encaissement.

La surveillance n'est pas facultative. Le manuel impose au participant à accès direct de consulter le service de portabilités et celui de revendications au moins une fois par minute. Il y détecte les changements de statut qui le concernent, comme reivindicador et comme doador. Un intégrateur qui passe par un PSP doit exiger l'exposition de cet événement, faute de quoi une revendication se signale d'abord par un client qui n'arrive plus à payer.

• Blocage judiciaire : quand une chave fait l'objet d'un blocage sur ordre de justice, le DICT renvoie EntryBlocked en HTTP 400 sur la consultation, la modification, la suppression, la portabilité et la revendication. Le participant doit répliquer ce blocage dans ses bases internes.
• Situation cadastrale irrégulière, personne physique : suspensa, cancelada, titular falecido, nula. Le Regulamento do Pix interdit alors le maintien de la chave.
• Situation cadastrale irrégulière, personne morale : suspensa, inapta, baixada, nula. Un CNPJ qui devient inapte perd ses chaves, donc son encaissement Pix, sans qu'aucune décision commerciale ait été prise.
• Exception MEI : pour un CNPJ de microempreendedor individual, la situation « suspensa » n'est pas traitée comme irrégulière lorsqu'elle résulte de l'article 1er de la Resolução CGSIM nº 36 du 2 mai 2016.
• Le nom doit correspondre mot pour mot au registre de la Receita Federal. Les tolérances sont limitatives : diacritiques d'une liste fermée, échange entre point, virgule, tiret, apostrophe et espace, et substitution du symbole & par la lettre E.

Chapitre 3. QR statique, cobrança immédiate, cobrança com vencimento.

Trois objets encaissent un Pix, et beaucoup d'équipes n'en câblent qu'un. Le QR statique ne passe par aucune API, se génère hors ligne et se réutilise sans limite. La cobrança immédiate (cob) porte un montant et une durée de vie courte. La cobrança com vencimento (cobv) porte une date d'échéance, et surtout des accessoires financiers que les deux autres n'ont pas. Choisir le mauvais objet coûte une ligne de code au départ, et une réconciliation impossible ensuite.

La cobv et ses quatre accessoires, à leur domaine exact

{
  "calendario": {
    "dataDeVencimento": "2026-09-10",
    "validadeAposVencimento": 30
  },
  "loc": { "id": 7891 },
  "devedor": { "cnpj": "12345678000195", "nome": "Empresa de Servicos SA" },
  "valor": {
    "original": "1250.00",
    "multa":      { "modalidade": 2, "valorPerc": "2.00" },
    "juros":      { "modalidade": 3, "valorPerc": "1.00" },
    "abatimento": { "modalidade": 1, "valorPerc": "50.00" },
    "desconto": {
      "modalidade": 1,
      "descontoDataFixa": [
        { "data": "2026-09-01", "valorPerc": "60.00" },
        { "data": "2026-09-08", "valorPerc": "25.00" }
      ]
    }
  },
  "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906"
}

• Le `loc` est typé. Un location créé pour une cobv ne peut pas porter une cob, et réciproquement : la spécification liste explicitement ces deux violations. Un location déjà utilisé par une autre cobrança est refusé.
• Les dates de remise doivent précéder l'échéance. Une entrée descontoDataFixa postérieure à dataDeVencimento fait rejeter la création.
• `validadeAposVencimento` se compte en jours et ne peut pas être négatif. Elle prolonge la payabilité au-delà de l'échéance, avec application de la multa et des juros.
• `modalidadeAlteracao` vaut 0 ou 1 : elle autorise ou non le payeur à modifier le montant, et pour une cobv la date d'échéance. À 0, un montant modifié côté application bancaire est refusé.
• Seule une cobrança `ATIVA` se modifie. Une requête qui tente d'altérer une cobrança dans un autre statut est rejetée.

Chapitre 4. Pix Automático : câbler un calendrier qu'on ne choisit pas.

Le récurrent Pix ne se pilote pas comme un prélèvement de carte. Le facturier n'ordonne pas un débit, mais envoie une instruction de paiement au PSP du payeur, qui la planifie et la liquide selon un calendrier fixé par la norme. Les horaires suivent l'heure de Brasília. Le bénéficiaire doit être une personne morale au CNPJ actif ; le récurrent est fermé aux bénéficiaires personnes physiques et aux facturations non périodiques (FAQ Pix Automático, Banco Central do Brasil).

• Le bénéficiaire peut annuler une cobrança jusqu'à la veille de la date de liquidation prévue. Passé ce point, l'annulation n'est plus possible, y compris pendant la période de retentatives postérieures à l'échéance.
• Une retentative porte un `txid` distinct de la tentative d'origine. Les tentatives se lisent dans l'objet tentativas de la cobrança recorrente, chacune avec son type (AGND pour l'échéance planifiée, NTAG pour une nouvelle tentative), sa date de liquidation, son endToEndId et son statut.
• Les intérêts et la pénalité d'un paiement en retard sont reportés sur la cobrança suivante. Ils ne se rattrapent pas sur l'échéance manquée.
• Une annulation d'autorisation ne casse pas l'échéance du jour. Les paiements planifiés pour le jour de l'annulation (et, si elle intervient après 22 h, pour le lendemain) doivent être acceptés.
• Le code d'erreur `UPAY` signale un paiement indu, faute de récurrence valide au moment de la liquidation. C'est le symptôme d'un désaccord entre l'état de l'autorisation chez le payeur et l'état de la récurrence dans votre référentiel.

L'identifiant de récurrence se lit sans appel d'API. Il fait exactement 29 caractères : deux lettres de préfixe, les huit chiffres de l'ISPB de l'agent qui l'a créé, une date yyyyMMdd, puis onze caractères alphanumériques uniques dans la journée. Le préfixe `RR` désigne une récurrence créée dans le Pix qui autorise les nouvelles tentatives après échéance ; `RN`, celle qui les refuse. Une supervision qui trie les abonnements sur ce préfixe sait, sans requête, lesquels sont récupérables après un impayé.

Chapitre 5. Devolução et MED : rembourser, contester, se défendre.

Trois chemins ramènent de l'argent en arrière sur le Pix, et un seul appartient au marchand. Le remboursement commercial part du bénéficiaire, la correction d'une panne part du PSP du bénéficiaire. Le MED part du payeur qui se dit victime d'une fraude, et il débite un compte sans son accord. Confondre les trois conduit à traiter une notificação de infração comme un litige carte, donc à répondre à côté.

Cette protection a une limite qui s'est déplacée. La version 4.1 du guide, applicable au 2 février 2026, a étendu le bloqueio cautelar aux personnes morales. Un compte de marchand peut donc être bloqué à titre conservatoire, pour 72 heures au plus, pendant que son PSP conduit une analyse plus poussée. Les plateformes sous-estiment un second effet. Une notificação de infração peut viser un intermédiaire de paiement, marketplace comprise, alors même que le destinataire final n'est pas lui. Le CNPJ qui reçoit collecte la réputation de fraude de ses vendeurs.

• `AnalysisResult` : agreed ou disagreed. En cas d'accord, le PSP maintient les fonds bloqués ; en cas de désaccord, il les libère.
• `FraudType`, obligatoire dès que AnalysisResult vaut agreed : application_fraud (compte ouvert avec les papiers d'un tiers), mule_account (compte ouvert légitimement puis prêté), scammer_account (compte au nom du fraudeur), other. La valeur other rend AnalysisDetails obligatoire.
• Une notification acceptée engendre automatiquement une marcação de fraude sur le bénéficiaire de la transaction visée. Annuler la notification annule la marcação ; revenir sur sa seule appréciation passe par CancelFraudMarker.
• Motifs de rejet d'une demande de restitution : no_balance (solde nul), account_closure (relation client terminée), invalid_request (réservé au motif de panne opérationnelle), other.
• Situations d'ouverture du MED, côté payeur : account_takeover, fraudulent_access, scam, coercion. Le paiement authentifié par mot de passe ou biométrie n'exclut aucune de ces situations.

Chapitre 6. Webhooks et réconciliation : trois flux, un seul ancrage.

L'API Pix n'expose pas un webhook mais trois, et ils ne s'abonnent pas de la même manière. Le premier suit les Pix reçus, chave par chave, tandis que les deux autres suivent le récurrent, l'un les récurrences, l'autre les cobranças recorrentes. Une intégration qui n'enregistre que le premier voit les paiements arriver et ignore l'état des abonnements qui les produisent.

• Les scopes sont granulaires et se demandent séparément : cob.write / cob.read, cobv.write / cobv.read, lotecobv.write / lotecobv.read, cobr, rec, solicrec, pix.write / pix.read, plus les trois paires de webhook.
• Un jeton de production ne doit porter que ce qu'il consomme. Le service qui crée des cobranças n'a aucun besoin de pix.write, qui commande les remboursements.
• Le canal de notification est protégé par mTLS. Le certificat client se vérifie côté marchand, et sa rotation se planifie comme celle d'un secret d'API.
• Le PSP peut grouper plusieurs Pix d'une même chave dans un seul appel. Le consommateur traite donc une liste, jamais un événement isolé, et reste idempotent sur chaque élément.

L'ancrage de la réconciliation n'est ni le montant ni la référence de commande, mais l'`EndToEndId`. Il fait exactement 32 caractères alphanumériques et circule dans les messages pacs.002, pacs.004 et pacs.008. Il identifie une liquidation, une seule, et il survit au remboursement puisque la devolução s'y rattache. Le txid, lui, compte de 26 à 35 caractères et n'est unique que par CPF ou CNPJ du bénéficiaire, règle que la spécification charge le PSP receveur de faire respecter.

GET /v2/pix?inicio=2026-09-01T00:00:00Z&fim=2026-09-01T23:59:59Z
          &cnpj=12345678000195
          &paginacao.paginaAtual=0&paginacao.itensPorPagina=100
Authorization: Bearer <jeton pix.read>

200 OK
{
  "parametros": {
    "inicio": "2026-09-01T00:00:00Z",
    "fim": "2026-09-01T23:59:59Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 4,
      "quantidadeTotalDeItens": 337
    }
  },
  "pix": [
    {
      "endToEndId": "E1234567820260901103100000001234",
      "txid": "655dfdb1a4514b8fbb58254b958913fb",
      "valor": "110.00",
      "horario": "2026-09-01T10:31:00.412Z"
    }
  ]
}

Reste la conception de la boucle de rattrapage. La spécification laisse à chaque PSP le soin de définir son propre engagement de service sur le déclenchement des callbacks, si bien qu'un webhook manquant n'est pas une anomalie contractuelle. Le référentiel de vérité est GET /pix, interrogé par fenêtres glissantes qui se chevauchent, avec déduplication sur l'EndToEndId. Trois journaux se rapprochent en fin de journée : les cobranças émises, les Pix liquidés, les devoluções exécutées. Le troisième est celui qu'on oublie, et il explique les écarts de trésorerie.

Chapitre 7. Limites nocturnes et antifraude : ce que le rail décide à votre place.

Les limites Pix ne sont pas un paramètre commercial du PSP, mais des règles normées qui coupent des paiements à des heures que le marchand ne choisit pas. L'Instrução Normativa BCB nº 512, du 30 août 2024, en fixe le régime : période nocturne, plafonds, délais de modification. Une équipe qui pilote un tunnel de paiement brésilien sans cette grille attribue à son parcours des abandons qui viennent du rail.

L'antifraude Pix : une réputation partagée, consultable avant de payer

Le DICT ne se contente pas de résoudre des chaves. Il tient un historique d'infractions consultable par les participants, sous le nom d'Estatísticas. Deux opérations y donnent accès. getEntryStatistics interroge une chave, getPersonStatistics un CPF ou un CNPJ. L'accès est réservé à l'initiative du participant. Le manuel interdit d'exposer cette fonctionnalité aux utilisateurs finals. Les données sont fraîches à douze heures près, la date du dernier événement figurant dans le champ watermark.

• Trois fenêtres temporelles sont renvoyées : les 90 derniers jours, les 12 derniers mois et les 60 derniers mois, ces deux dernières sans le mois en cours.
• Interroger une chave renvoie deux jeux : ceux de la chave, et ceux du CPF ou du CNPJ qui lui est rattaché. Un fraudeur qui change de chave ne change pas de titulaire.
• Supprimer une chave n'efface rien. Le manuel précise que suppression, modification, portabilité et revendication ne retirent ni n'invalident les informations de notification d'infraction.
• Une chave réenregistrée hérite de l'historique dès lors que l'ensemble des informations de chave et d'utilisateur est identique à celui de la chave supprimée.
• La marcação de fraude transacional existe hors du MED : un PSP peut marquer un client fraudeur via CreateFraudMarker, y compris pour un Pix liquidé hors SPI ou rejeté, et il annule sa marque quand il le souhaite.