🔁 La machine à états d'un paiement

Les états d'un paiement et leurs transitions légitimes

L'état d'un paiement désigne la position qu'il occupe dans la suite d'opérations conduisant d'une demande initiale à un mouvement de fonds définitif. Chaque acteur de la chaîne tient sa propre version de cette position, et ces versions ne coïncident jamais tout à fait. L'émetteur connaît une réservation de provision, l'acquéreur une présentation en compensation, le prestataire un objet de son API doté de son propre vocabulaire. Le marchand connaît une commande. Cet objet n'existe dans aucun des systèmes précédents. La machine à états de cette commande doit donc être tenue par le système marchand lui-même. Aucun autre acteur ne la rapproche des opérations exécutées sur les rails.

Sur le rail carte, les transitions légitimes sont portées par des messages normalisés dont ISO 8583 fixe le répertoire. Une demande d'autorisation part en 0100 et revient en 0110. Une annulation d'autorisation emprunte le 0400 quand elle attend une réponse synchrone, le 0420 répété en 0421 quand elle se contente d'un acquittement 0430. Sur un schéma à double message, la capture ne circule pas dans ces messages. Elle passe par la remise en compensation, qui est un traitement de fichier. Le règlement des fonds suit encore après. Ces quatre étapes se déroulent dans quatre systèmes distincts, dotés chacun de son propre calendrier de traitement. Les réseaux de débit à message unique fusionnent au contraire l'autorisation et la compensation, ce qui referme la fenêtre de capture et supprime les états qu'elle ouvre.

Les spécifications EMVCo placent une machine à états supplémentaire dans la puce de la carte, en deçà des messages qui circulent sur le réseau. La carte produit un cryptogramme de demande, l'ARQC, que l'émetteur vérifie et auquel il répond par un ARPC. La carte tranche ensuite au second GENERATE AC, en rendant un TC lorsqu'elle accepte la transaction et un AAC lorsqu'elle la refuse. Un accord de l'émetteur ne suffit donc pas à conclure la transaction. La décision finale revient à la puce. Le terminal doit lire ce dernier cryptogramme avant de déclarer un résultat à la caisse. Un journal de caisse qui enregistre l'accord de l'émetteur sans lire le cryptogramme final déclare acceptées des transactions que la carte a refusées, et l'écart n'apparaît qu'au moment de la compensation.

Les rails à règlement immédiat comportent peu d'états intermédiaires. Un virement instantané est accepté ou rejeté, sans réservation préalable ni fenêtre de capture. L'autorisation carte est une promesse révocable, alors que le virement instantané abouti constitue un mouvement de fonds définitif. La différence porte sur la réversibilité. De cette propriété dépend toute la conception de la machine à états. Un système qui applique le même diagramme aux deux familles de rails se trompe sur ce point. Une commande réglée par le client sur un rail instantané ne se corrige que par un remboursement, opération nouvelle et volontaire, jamais par une annulation technique.

L'idempotence : quelle clé, quelle portée, quelle rétention

L'idempotence est la propriété d'une opération dont plusieurs exécutions successives produisent le même résultat qu'une exécution unique. Les interfaces de paiement l'emploient pour une situation fréquente, celle d'une soumission partie dont la réponse n'est jamais revenue. L'appelant ignore alors si l'opération a eu lieu. Le rejeu doit produire le même résultat que la première tentative, sans créer un second paiement. Le mécanisme repose sur une clé fournie par l'appelant, que le serveur associe au résultat de la première exécution et restitue à l'identique aux tentatives suivantes. Il ne va pas au-delà. Il détermine ce que produit une seconde soumission portant la même clé, et laisse entière la décision d'accepter ou de refuser le paiement.

La clé se dérive de l'intention métier, jamais de la tentative technique. Une clé tirée au hasard à l'intérieur de la boucle de reprise laisse passer les doublons, puisque chaque essai en porte une nouvelle. Elle se produit au moment où l'intention naît, se persiste avec la commande, puis sert à toutes les tentatives de cette commande. Stripe accepte des clés jusqu'à 255 caractères, recommande un UUID de version 4 et écarte explicitement les données personnelles comme matériau de clé (Stripe, documentation API, consultée en août 2026). Adyen limite la sienne à 64 caractères et recommande également un UUID (Adyen, documentation développeur, consultée en août 2026). Une intégration multi-prestataires dont la clé serait construite une fois pour toutes, à la longueur du plus permissif des deux, verrait ses appels rejetés par l'autre.

La portée d'une clé d'idempotence désigne l'ensemble à l'intérieur duquel sa valeur doit rester unique. Elle est le paramètre le moins documenté du mécanisme, et le plus piégeux. Une clé est unique dans l'espace d'un identifiant d'API et d'un point d'entrée, pas dans l'absolu. La documentation le dit rarement. La portée se déduit du modèle d'authentification, chaque jeu d'identifiants délimitant un espace de clés distinct chez le prestataire. La même valeur envoyée à un autre prestataire, ou sur un autre point d'entrée du même prestataire, désigne une opération différente. Un basculement de route après échec crée donc un second paiement, quelle que soit la clé portée, parce que le second acquéreur n'a jamais vu la première tentative. La protection contre les doublons d'une cascade est mise en œuvre par le système marchand, aucun prestataire ne connaissant les tentatives adressées à ses concurrents.

La durée de rétention est l'intervalle pendant lequel le prestataire conserve une clé et le résultat qui lui est associé. Elle détermine le comportement du système après une longue panne. Stripe indique que les clés peuvent être supprimées passé vingt-quatre heures, et qu'une clé réutilisée après cette purge produit une requête neuve. Adyen annonce une validité d'au moins sept jours après la première soumission. PayPal emploie l'en-tête PayPal-Request-Id, renvoie l'état de la requête précédente et renvoie la durée de conservation à la documentation de chaque API. Une file de reprise redémarrée au bout de quarante-huit heures se situe donc au-delà de la première fenêtre et à l'intérieur de la deuxième. Cette durée se lit avant l'écriture de la politique de reprise, et se relit à chaque changement de prestataire. Elle borne l'intervalle au-delà duquel une nouvelle soumission crée un paiement supplémentaire au lieu de restituer le premier résultat.

Le comportement en cas de conflit relève de l'usage plus que d'une norme opposable. Stripe compare les paramètres entrants à ceux de la requête d'origine et renvoie une erreur lorsqu'ils diffèrent. Adyen répond 409 ou 422 avec le code d'erreur 704 quand deux requêtes portant la même clé arrivent simultanément. Le groupe de travail HTTPAPI de l'IETF a porté un projet destiné à fixer ces conventions, draft-ietf-httpapi-idempotency-key-header, dont la version 07 est datée du 15 octobre 2025 et a expiré le 18 avril 2026. Le texte n'est jamais devenu une RFC. Rien n'oblige un prestataire à le suivre. Il retient trois réponses. Un 400 sanctionne l'absence de l'en-tête requis, un 422 la clé rejouée avec une charge utile différente, un 409 le rejeu qui précède la fin de la requête d'origine. Stripe documente pour sa part le moment où le résultat idempotent est enregistré. Aucun résultat ne l'est tant que l'exécution n'a pas commencé, et une requête refusée à la validation des paramètres peut donc être renvoyée telle quelle.

1. ecrire en base l'intention de paiement, PUIS valider la transaction
   (id_commande, montant, devise, cle_idempotence, etat = SOUMISSION_EN_COURS)
   -> le commit precede tout appel reseau, sans exception

2. appeler le prestataire en portant cette cle
   reponse 2xx     -> etat = AUTORISE, stocker l'identifiant prestataire
   reponse 4xx      -> etat = REFUSE, stocker le code recu
   timeout ou 5xx   -> etat INCHANGE, la ligne reste SOUMISSION_EN_COURS

3. un travail de fond reprend toute ligne restee SOUMISSION_EN_COURS
   dans la fenetre de retention -> rejeu avec LA MEME cle
   au-dela de la fenetre        -> interrogation de l'etat, jamais un nouvel appel

4. la cle se compose de l'identifiant de commande et d'un numero de tentative
   LOGIQUE (une re-presentation deliberee = nouvelle tentative = nouvelle cle),
   jamais d'un condense du montant et de la date, qui collisionne

L'idempotence protège la soumission de la requête. Le paiement lui-même reste hors de son champ. Quatre limites bornent sa portée, et chacune se vérifie avant la mise en production.

• Elle ne remonte pas jusqu'au réseau. Une clé rejouée évite un second appel d'API. Elle n'annule pas une autorisation déjà obtenue par la première tentative, dont la neutralisation passe par une annulation d'autorisation 0420, répétée jusqu'à l'acquittement 0430.
• Elle ne franchit pas la frontière du prestataire. Une cascade vers un second acquéreur sort du domaine d'unicité de la clé, si bien que deux autorisations peuvent coexister sur le compte du porteur.
• Elle ne survit pas à sa fenêtre de rétention. Passé le délai annoncé par le prestataire, un rejeu n'est plus un rejeu, mais une création.
• Elle ne protège pas d'une collision métier. Deux intentions distinctes qui produisent la même clé font disparaître un paiement, sans erreur ni alerte, et le manque n'apparaît qu'à la réconciliation.

Les notifications asynchrones : ordre, rejeu, signature, acquittement

La notification asynchrone est un message que le prestataire adresse à un point d'entrée du marchand lorsqu'un état change chez lui. Ce message signale le changement sans en constituer le registre. Le prestataire le retente si l'accusé de réception n'arrive pas, dans une fenêtre qu'il borne lui-même, et ne garantit ni l'ordre de livraison ni l'unicité. Stripe l'écrit dans sa documentation, la livraison ne suit pas l'ordre de génération des événements et un même point d'entrée peut recevoir plusieurs fois le même message. Un système marchand qui reconstitue son état à partir de la seule séquence reçue obtient donc un état faux, sans qu'aucune erreur soit levée ni qu'aucune trace apparaisse dans les journaux. L'écart se découvre à la réclamation d'un client ou à la réconciliation du lendemain.

Le désordre de livraison désigne la réception d'une notification ancienne après une notification plus récente. La situation est courante, une même opération produisant plusieurs événements émis à quelques millisecondes d'intervalle et livrés par des chemins réseau indépendants. La notification d'échec d'une tentative arrive parfois après celle du succès de la tentative suivante. La protection repose sur une règle unique. À chaque réception, une notification ne fait avancer l'état que si la transition est légitime depuis l'état courant, et toute transition illégitime est journalisée puis abandonnée. Quand le prestataire horodate ses événements, l'horodatage sert de second garde, un message plus ancien que l'état courant ne pouvant plus le rétrograder.

L'authentification de la notification distingue un message émis par le prestataire d'un message forgé par un tiers, et aucun autre contrôle n'établit cette distinction. Stripe signe chaque envoi dans un en-tête Stripe-Signature, qui porte un horodatage préfixé t= et une ou plusieurs signatures préfixées v1=. La signature est un HMAC-SHA256 calculé sur la concaténation de l'horodatage, d'un point et du corps brut de la requête. Le corps doit être lu avant tout traitement par un cadriciel web, parce qu'une simple réécriture d'espaces invalide la vérification. Les bibliothèques officielles rejettent par défaut un horodatage vieux de plus de cinq minutes, ce qui borne la fenêtre de rejeu d'un message intercepté. Lors d'une rotation de secret, deux secrets restent actifs jusqu'à vingt-quatre heures et l'envoi porte alors une signature par secret. Stripe publie aussi la liste des adresses depuis lesquelles il émet, et recommande de combiner le filtrage réseau et la vérification de signature plutôt que de choisir entre les deux.

L'accusé de réception est le code de statut que le point d'entrée marchand renvoie au prestataire. Sa valeur détermine la suite du cycle. Un code 2xx arrête les reprises, tout le reste les déclenche, et une redirection 3xx compte comme un échec chez Stripe. La séquence recommandée vérifie la signature, écrit l'événement brut dans une file, répond 2xx, puis traite hors du cycle de requête. Traiter avant de répondre expose au dépassement de délai, donc à une reprise, donc à un doublon. Stripe retente pendant trois jours en production, avec un espacement croissant. Le renvoi manuel reste possible pendant quinze jours depuis l'interface, trente jours depuis l'outil en ligne de commande. Adyen demande d'accepter le message par un 2xx, de le stocker, puis seulement d'en traiter le contenu.

La file d'attente morte est la file où sont déposés les messages que le traitement n'a pas su absorber. Elle remplit deux fonctions. Elle empêche qu'un message empoisonné bloque la file principale, et elle rend visible ce qui a échoué. Une file morte dépourvue de propriétaire nommé et d'alerte sur son âge accumule des messages que personne ne reprend, et les paiements concernés restent dans un état périmé. Le rejeu depuis cette file repasse par le même contrôle de transition que la voie normale, sous peine de faire avancer un état que la voie normale avait justement refusé.

Reprendre par interrogation : la notification n'est jamais la source de vérité

La reprise par interrogation consiste à demander périodiquement au prestataire l'état courant des paiements dont l'issue reste inconnue. Elle complète le canal de notification, qui accélère la connaissance d'un changement sans en garantir la livraison. Les trois prestataires cités plus haut bornent leurs reprises dans le temps, et aucun ne promet une livraison en toutes circonstances. Un point d'entrée indisponible trois jours d'affilée sort de la fenêtre de reprise automatique d'un prestataire qui retente pendant trois jours. Les événements de la période ne reviennent alors que par un renvoi manuel, tant qu'il reste ouvert, ou par une interrogation. La source de vérité est l'état détenu par celui qui exécute le paiement. Il s'obtient en le lui demandant.

L'interrogation porte sur les paiements laissés dans un état non terminal, ordonnés par ancienneté, avec un espacement croissant entre deux tentatives, plutôt que sur un balayage de toute la base à intervalle fixe. La cadence se cale sur la durée de vie attendue de l'état, et cette durée varie de quelques secondes à plusieurs jours selon le rail emprunté. Un paiement instantané qui n'a pas conclu au-delà du délai butoir de son rail est anormal. Une autorisation carte en attente de capture ne l'est pas avant plusieurs jours. Une cadence unique produit donc deux défauts. Elle multiplie les appels inutiles sur les états dont la durée normale est longue, et elle détecte trop tard les incidents sur les états dont la durée de vie se compte en secondes.

Le protocole qui relie la caisse au terminal a formalisé le même besoin de longue date. Dans le protocole Retailer de nexo Standards, chaque paire requête-réponse porte un ServiceID, identifiant court que la spécification recommande de tenir sur dix caractères et dont l'unicité incombe à la caisse qui l'émet. La clé d'idempotence d'une API web et cet identifiant ne se construisent donc pas de la même façon, l'un tolérant un UUID que l'autre ne peut pas porter. Quand la réponse de paiement ne revient pas, la caisse n'émet pas une seconde demande. Elle envoie une requête d'état de transaction portant le ServiceID d'origine, et le terminal lui restitue la dernière réponse qu'il a produite pour ce couple de caisse et de terminal. Si la transaction est toujours en cours, la réponse porte un résultat d'échec assorti de la condition Busy, qui appelle une nouvelle interrogation et ne vaut pas refus. Une caisse qui traite cette condition comme un refus émet une seconde demande de paiement et encaisse le client deux fois.

Sur les rails instantanés, l'absence de réponse dans le délai imparti vaut décision de rejet. Le schéma SCT Inst de l'European Payments Council fixe un temps d'exécution maximal de dix secondes. Une échéance ferme de vingt secondes court à compter de l'horodatage posé par la banque du donneur d'ordre, et la transaction doit être rejetée au-delà par les intervenants de la chaîne. Un pacs.002 absent dans la fenêtre vaut donc rejet, jamais attente. Aux États-Unis, le service FedNow de la Réserve fédérale applique un compteur de vingt secondes. Chaque banque réceptrice s'en réserve de une à cinq secondes, selon sa capacité à traiter le message (Federal Reserve, Understanding the payment timeout clock). Un délai d'expiration applicatif plus court que ces bornes conduit le marchand à tenir pour incertaine une opération qui a abouti.

Le rail carte porte sa propre reprise, plus ancienne que les API web et construite sur le même principe. Un terminal qui n'obtient pas de 0110 dans le délai imparti ne suppose pas le refus. Il émet une annulation d'autorisation en 0420, répétée en 0421 jusqu'à l'acquittement 0430, généralement depuis une file locale de type store-and-forward. La différence avec l'interrogation porte sur le sens de l'opération. Le terminal ne demande pas l'état, il impose l'annulation d'un état qu'il ne connaît pas, ce qui reste sans effet si l'émetteur n'avait rien autorisé.

• Interroger par état, pas par table. La requête de reprise porte sur les états non terminaux et sur eux seuls, avec un index dédié ; un balayage complet devient impraticable dès les premiers millions de lignes.
• Espacer les tentatives. Un espacement croissant, borné par un plafond, évite qu'un incident de disponibilité chez le prestataire se transforme en attaque par déni de service émise par le marchand.
• Traiter la réponse comme une notification. Le résultat de l'interrogation passe par le même contrôle de transition, faute de quoi deux chemins d'écriture appliquent deux règles différentes au même état.
• Journaliser l'origine de chaque transition. Notification, interrogation, réconciliation ou action humaine ; sans cette trace, aucun incident de statut n'est explicable après coup.

Les paiements coincés entre autorisation, capture, règlement et remboursement

Un paiement coincé est un paiement immobilisé dans un état non terminal au-delà de la durée normale de cet état. Ces paiements forment le résidu ordinaire d'une chaîne où plusieurs systèmes avancent à des vitesses différentes, et leur volume mesure la qualité de l'intégration mieux qu'un taux d'acceptation. Chacun possède une signature reconnaissable, une requête qui le détecte et une action corrective qui lui est propre. Un traitement de masse, par balayage unique et sans distinction de cas, produit les doublons que la reprise cherchait à supprimer.

Le cas le plus courant est l'autorisation jamais capturée. La provision reste réservée chez l'émetteur, invisible dans les outils du marchand et bien visible pour le porteur, qui la prend pour un débit. L'expiration de cette autorisation a un coût. Les réseaux facturent l'autorisation restée sans suite. Les délais de présentation en compensation varient selon le segment marchand, et ils figurent dans les Visa Core Rules comme dans les Mastercard Rules, publiées et révisées périodiquement. Ces délais se lisent dans l'édition en vigueur, jamais dans un mémo interne recopié d'année en année, que cette révision périodique prive de valeur. L'action corrective consiste à émettre une annulation d'autorisation dès l'abandon de la commande, sans attendre l'expiration.

La capture sans règlement désigne une capture acceptée par le prestataire qui n'a donné lieu à aucun versement. Elle se détecte dans les fichiers plutôt que dans l'API. Une capture acceptée n'entre pas mécaniquement dans un lot de versement, puisqu'un rejet en compensation, un lot bloqué ou une retenue de réserve peuvent l'en écarter. Le symptôme est un paiement marqué réglé côté marchand et absent du rapport de règlement de la journée correspondante. La détection croise donc l'état interne et le fichier de l'acquéreur. Une capture partielle complique encore la lecture, puisqu'elle laisse un reliquat d'autorisation qu'il faut annuler séparément pour libérer la provision restante.

Le remboursement sans capture correspondante est le cas le plus dangereux, parce qu'il déplace de l'argent réel dans le mauvais sens. Il naît d'un opérateur qui rembourse une commande annulée dont l'autorisation n'a jamais été présentée, ou d'un script de reprise mal borné qui rejoue une file entière. Le crédit part sans vente à laquelle l'adosser. Les réseaux encadrent le crédit sans transaction d'origine, précisément parce qu'il sert aussi à vider un compte marchand compromis. La règle qui ferme le sujet subordonne tout remboursement à la référence d'une capture réglée, et plafonne le cumul des remboursements d'une commande au montant capturé.

L'expiration d'autorisation est la fin de la réservation de provision chez l'émetteur. Cet état ne s'accompagne d'aucun message. Aucun réseau ne prévient le marchand que la réservation est tombée. La durée dépend de l'émetteur, du type d'autorisation, une autorisation estimée n'étant pas une autorisation finale, et du segment marchand. Elle ne se code jamais en dur dans le système marchand. Ce dernier porte sa propre échéance, plus courte que la plus courte des durées observées sur son portefeuille, et traite le dépassement comme une commande à ré-autoriser plutôt qu'à capturer.

La réconciliation d'événements comme filet de sécurité

La réconciliation d'événements est la comparaison périodique de l'état d'un même paiement dans les systèmes qui le suivent. Elle précède la réconciliation des montants, qui compare le versement reçu en banque au net calculé par le prestataire et relève d'une chaîne comptable distincte. La première porte sur trois jeux de données qui devraient dire la même chose au même moment. Elle rattrape ce que le canal de notification a perdu, avant que l'écart n'atteigne le grand livre et ne devienne un sujet de clôture. Les deux exercices se complètent sans se recouvrir, l'un vérifiant des montants et l'autre des états, et une chaîne qui n'en tient qu'un découvre ses trous par la comptabilité.

Trois jeux de données se confrontent. L'état porté par le système marchand, la liste des paiements telle que le prestataire l'expose par son API ou par un export daté, et le fichier de règlement de l'acquéreur. Un paiement doit apparaître dans les trois, dans des états compatibles entre eux. Toute ligne présente dans un jeu et absente d'un autre est un écart, et chaque type d'écart désigne une cause dominante différente.

Les écarts se rangent en quatre familles. Leur répartition renseigne mieux qu'un taux global. La notification jamais reçue laisse un état figé chez le marchand alors que le prestataire est passé à l'état suivant. La notification reçue puis perdue en traitement produit le même symptôme, tout en laissant une trace dans les journaux d'acquittement, ce qui la distingue de la précédente. Le changement d'état sans notification correspondante concerne surtout les contestations et les opérations à l'initiative de l'émetteur. L'état avancé sans contrepartie chez le prestataire révèle un défaut du code marchand ou une intervention manuelle, situation qu'aucun prestataire n'est en mesure de signaler.

La fenêtre de réconciliation se cale sur la durée des reprises du prestataire plutôt que sur la journée comptable. Un prestataire qui retente pendant trois jours livrera le mardi un événement du samedi, et une réconciliation strictement quotidienne comptera deux fois l'écart correspondant. La pratique consiste à passer chaque jour sur les dernières vingt-quatre heures, puis à repasser chaque semaine sur une fenêtre plus large, avec un état de résolution et un responsable attachés à chaque écart. L'export utilisé doit lui-même être borné par des dates et rejouable sans effet, sous peine de créer les écarts qu'il devait mesurer. Un écart encore ouvert au-delà de sa fenêtre est traité comme un incident, avec un responsable désigné et une échéance de résolution.

• Âge du plus ancien paiement non terminal, par état et par prestataire. L'indicateur monte avant tous les autres quand un canal de notification tombe, et il monte même si le volume d'écarts reste faible.
• Nombre d'états marchands sans événement correspondant chez le prestataire, sur la fenêtre longue. Une valeur non nulle qui persiste désigne un défaut de code, jamais un aléa réseau.
• Profondeur et âge de la file d'attente morte. Une file qui se vide toute seule ne prouve rien, parce que seul son âge maximal renseigne sur ce qui a été réellement traité.
• Taux d'événements rejetés pour transition illégitime. Une hausse signale un changement de vocabulaire chez le prestataire, souvent annoncé dans une note de version que personne n'a lue.
• Écart entre le nombre de captures internes et le nombre de lignes du rapport de règlement, par journée. Il ferme la jonction avec la réconciliation des montants et se surveille au même titre.