Notification de paiement en double : contrôler les traitements de la commande

Recevoir deux notifications ne suffit pas à conclure que le client a payé deux fois. Le contrôle utile consiste à retrouver le paiement, la commande concernée et l’action déjà exécutée : préparation, ouverture d’un accès, réservation ou envoi d’une confirmation. Avant d’autoriser une reprise, l’équipe doit savoir quel effet elle risque de déclencher à nouveau.

Cette question mérite une recette avec l’intégrateur. Stripe documente des livraisons répétées et un ordre de réception non garanti. Son guide Checkout précise aussi que la fonction chargée d’exécuter la commande peut être appelée plusieurs fois, y compris simultanément, pour la même session. Ce sont des comportements de Stripe ; un autre prestataire exige la lecture de sa propre documentation. Sources : réception des événements Stripe et exécution des commandes Checkout.

Séparer le paiement, le message et l’action métier

Le prestataire de paiement décrit l’état d’une opération financière. La plateforme commerce porte la commande. Une notification serveur, ou webhook, transmet un événement entre systèmes. Le service de préparation ou de délivrance conserve encore un autre état : ce qui a effectivement été fait.

Ces informations doivent pouvoir être rapprochées, sans être confondues. Une même notification reçue à nouveau ne crée pas nécessairement un nouveau paiement. À l’inverse, deux événements différents peuvent concerner une seule commande et demander des actions distinctes. Le journal doit donc relier l’identifiant d’événement, l’objet du prestataire, la commande interne et l’effet métier envisagé.

Un statut HTTP de succès renvoyé à Stripe n’est pas une preuve que la préparation est terminée. Il renseigne la livraison du message à votre point de réception. Pour savoir si l’action a abouti, il faut la trace du système qui l’exécute.

Le choix du moyen et son délai de confirmation relèvent d’un autre arbitrage, traité dans Quels moyens de paiement proposer en France ?. Ici, le but est de protéger les traitements qui suivent cette confirmation.

Vérifier l’origine et conserver une réception exploitable

Stripe demande de vérifier la signature des notifications avec le corps brut de la requête, l’en-tête Stripe-Signature et le secret du point de réception concerné. Modifier le corps avant cette vérification peut la faire échouer. Une signature invalide ne doit pas déclencher la préparation d’une commande. Source : vérification des événements Stripe.

La documentation recommande également une réponse HTTP de succès rapide et un traitement au moyen d’une file asynchrone. La question à poser à l’intégrateur est alors précise : qu’est-ce qui est conservé durablement avant que le serveur accuse réception ? Si le serveur répond favorablement puis s’arrête avant d’avoir confié le travail à un mécanisme de reprise, l’action peut rester à faire sans être visible dans la livraison Stripe.

La recommandation opérationnelle est de distinguer reçu, à traiter, en cours, terminé et en erreur, avec des libellés adaptés au système réel. Le registre doit permettre de trouver le travail restant, pas seulement de compter les réponses HTTP. Ces états sont une méthode proposée ; leur présence n’est pas attestée dans votre intégration.

Reconnaître une répétition sans bloquer une action légitime

Stripe recommande de conserver les identifiants des événements déjà traités pour éviter de retraiter la même livraison. La documentation distingue aussi le cas où des objets Event séparés sont générés : l’identifiant de l’objet dans data.object et le type d’événement aident à repérer ces doublons. Source : traitement des événements répétés.

Ces deux contrôles ne répondent pas exactement à la même question. L’identifiant de l’événement permet de reconnaître un message déjà rencontré. La protection d’une action métier doit, elle, porter sur ce qui ne doit pas être exécuté deux fois.

Il faut donc demander à l’intégrateur quelle opération est protégée et quelle référence la représente. Une préparation initiale, un remboursement partiel et une nouvelle tentative autorisée ne peuvent pas être confondus parce qu’ils concernent la même commande. Le couple objet/type ne doit pas devenir une règle générale qui supprime indéfiniment toute nouvelle notification correspondante sans examiner son rôle dans le cycle réel.

L’ordre des messages demande un contrôle séparé. Stripe ne garantit pas leur livraison dans l’ordre de création et déconseille d’utiliser le champ created comme preuve d’ordre ou de déduplication. Sa documentation prévoit de récupérer les objets nécessaires par l’API lorsque le traitement en a besoin. Un message ancien ne doit pas, à lui seul, faire reculer un état métier déjà confirmé. La règle applicable à une commande annulée ou modifiée doit être définie avec l’équipe opérations.

Dans l’exemple Stripe Checkout, le guide demande de récupérer la session et de vérifier payment_status avant l’exécution. Il traite aussi les moyens à confirmation différée au moyen d’événements asynchrones. Il serait donc insuffisant de considérer toute fin de parcours navigateur comme une autorisation de préparation. Source : guide Checkout.

Prévoir les appels simultanés et la panne au mauvais moment

Un contrôle « cette commande est-elle déjà traitée ? » suivi d’un lancement ne suffit pas si deux traitements peuvent lire la même réponse avant qu’un seul ait écrit son résultat. La recette doit couvrir ce cas, explicitement signalé dans le guide Checkout.

Demandez comment le système réserve le droit d’exécuter une opération entre plusieurs traitements concurrents. Le contrôle et cette réservation doivent être coordonnés de façon atomique : pour l’opération protégée, deux exécutants ne doivent pas obtenir séparément la même autorisation. La solution technique dépend de l’intégration ; une simple liste d’identifiants relue sans protection de concurrence ne démontre pas ce résultat.

La panne pose ensuite deux questions différentes. Si le service s’arrête après avoir réservé le travail mais avant de l’exécuter, quelqu’un doit pouvoir identifier et reprendre l’état « en cours ». Marquer définitivement l’action comme terminée dès sa réception éviterait peut-être une répétition, mais pourrait perdre un traitement nécessaire.

Si le service externe a déjà exécuté l’action puis que la confirmation locale se perd, une reprise aveugle risque au contraire de la répéter. Il faut alors pouvoir retrouver l’opération dans le service destinataire ou réutiliser son mécanisme d’idempotence, lorsqu’il en fournit un et que ses conditions sont respectées. Sans moyen de lever l’incertitude, le dossier doit passer en vérification, plutôt que déclencher automatiquement une nouvelle action.

Cette coordination est une exigence de recette proposée pour le flux complet. Le guide Stripe ne certifie ni votre file de travail, ni votre base de données, ni le comportement de votre prestataire de préparation.

Ne pas confondre clé d’idempotence et preuve d’exécution

Une clé d’idempotence sert à répéter une requête sans demander une nouvelle fois la même opération, dans les conditions prévues par l’API destinataire. Elle ne remplace ni la vérification du message entrant ni le suivi de l’effet métier.

La documentation actuelle de Stripe sur l’idempotence distingue notamment ses API v1 et v2. Pour l’API v1, une réponse mémorisée peut être renvoyée avec la même clé, y compris lorsqu’il s’agit d’une erreur 500. Stripe demande de traiter l’issue d’une erreur 500 comme indéterminée : des effets peuvent avoir eu lieu. Il faut les rapprocher avant de tenter une nouvelle opération avec une autre clé. Source : erreurs HTTP et reprises Stripe.

Pour chaque appel sortant, l’intégrateur doit expliquer quelle action la clé représente, comment elle est conservée, pendant quelle durée le service la reconnaît et comment une erreur est rapprochée de l’état réel. Si la destination n’est pas Stripe, ses règles sont à vérifier séparément. Une clé créée à nouveau à chaque tentative ne représente plus une répétition de la même requête.

Commander une recette qui couvre les reprises

La recette suivante est à exécuter dans un environnement de test autorisé, avec des événements et commandes de test. Elle ne constitue pas un test déjà effectué sur votre boutique.

1. Même événement reçu à nouveau. Relever les deux réceptions et vérifier le nombre d’effets métier réellement produits, pas seulement le nombre de messages ignorés.
2. Deux traitements simultanés pour la même opération. Vérifier qu’un seul obtient le droit de la lancer et que l’autre retrouve un état explicable, sans bloquer une action différente et légitime.
3. Événements distincts sur une même commande. Examiner lesquels décrivent une répétition et lesquels demandent une nouvelle action autorisée. Conserver la justification de la décision.
4. Réception tardive ou ordre inversé. Vérifier que le traitement rapproche les états nécessaires sans réactiver une commande annulée ni écraser aveuglément une information plus récente.
5. Interruption avant ou après l’effet externe. Tester la reprise du travail réservé mais non exécuté, puis le cas où l’effet a réussi sans confirmation locale. Vérifier comment l’incertitude est levée.
6. Origine non validée. Vérifier qu’un message dont la signature est invalide ne déclenche aucun effet métier et laisse une trace d’erreur exploitable.

Pour chaque cas, conserver l’état initial, l’action protégée, le résultat attendu, le résultat obtenu et le responsable de la reprise. Le dossier n’est clos que lorsque les écarts sont expliqués ou restent explicitement ouverts. Aucun taux universel de doublons ou de réussite n’est nécessaire pour conduire cette vérification.

Le responsable e-commerce fixe les effets à protéger et les cas qui demandent une décision humaine. L’intégrateur apporte les traces et les preuves de reprise. Cette recette ne promet pas un traitement « exactement une fois » dans tous les systèmes ; elle permet de vérifier les garanties du flux réellement utilisé.

Documentation Stripe consultée le 23 octobre 2026. Les scénarios ci-dessus sont des cas de recette proposés, pas des incidents observés ni des tests exécutés sur une boutique.