Un client termine son paiement, arrive sur une page de remerciement et ferme son navigateur. À quel moment votre application doit-elle autoriser la préparation de sa commande ? La réponse demande de distinguer ce que voit le client, ce que confirme Stripe et ce que votre propre système a enregistré. Si ces trois éléments sont confondus, une commande peut partir trop tôt ou rester bloquée malgré un paiement réussi. Le bon point de départ est une règle métier explicite sur les preuves nécessaires au passage à l’état payé.
Décrire les états avant les événements techniques
Écrivez les états que l’équipe comprend : commande créée, paiement en cours, paiement confirmé, préparation autorisée, annulée et remboursée. Précisez ce que chaque état permet de faire. Une commande créée réserve-t-elle du stock ? Qui peut déclencher un envoi ? Un remboursement annule-t-il automatiquement une préparation déjà commencée ? Ces questions doivent être résolues avec les personnes concernées avant de choisir les événements à écouter.
Dans un exemple fictif, une entreprise vend un atelier avec un nombre de places limité. L’arrivée sur une page de succès ne suffit pas à garantir une place si le paiement n’a pas encore été confirmé. Inversement, un client dont le paiement est confirmé doit pouvoir retrouver sa réservation même s’il ferme la fenêtre avant le retour sur le site. L’état commercial doit donc être conservé sur le serveur et relié à une référence de commande stable.
Traiter le retour navigateur comme une information d’interface
La page de retour sert à expliquer la suite au client. Elle peut afficher un statut issu de votre serveur et proposer un accès à la commande. Elle ne devrait pas marquer arbitrairement une commande payée à partir d’un paramètre d’URL ou d’un bouton. Le navigateur peut être interrompu, la connexion peut tomber et le client peut revenir plusieurs fois sur la même adresse.
Préparez un message adapté au paiement encore en cours : la demande a été reçue et la confirmation sera consultable dans l’espace prévu. Évitez un texte qui affirme « paiement validé » avant la vérification. La rédaction fait partie de la fiabilité du parcours : elle réduit les relances inutiles et empêche qu’un écran optimiste soit interprété comme une preuve de réservation définitive.
Recevoir les confirmations côté serveur
Stripe décrit les webhooks comme des notifications envoyées à votre serveur lorsqu’un événement survient. Sa documentation officielle précise notamment la vérification de signature, la possibilité de doublons et l’absence de garantie d’ordre de livraison. Ces propriétés imposent de traiter une notification comme un message à contrôler, plutôt que comme une commande à exécuter aveuglément.
Le serveur doit rapprocher l’objet de paiement de la commande attendue, vérifier les éléments nécessaires et appliquer une transition autorisée. Le type d’événement et les statuts à utiliser dépendent du parcours de paiement retenu. Conservez une référence stable entre les systèmes pour éviter un rapprochement approximatif par nom ou montant. Deux commandes de même valeur ne sont pas interchangeables, même lorsqu’elles appartiennent au même client.
Accepter deux fois le message, exécuter une seule fois l’action
Imaginons que le même événement soit reçu deux fois. Le système peut répondre correctement aux deux livraisons tout en ne créant qu’une seule préparation. Cela demande une trace durable de ce qui a été traité et une protection contre deux traitements simultanés. Vérifier simplement « existe déjà » puis créer n’est pas toujours suffisant si deux exécutions font le contrôle au même moment. Le mécanisme retenu doit être cohérent avec votre base de données.
Prévoir les interruptions au milieu du traitement
Une intégration peut enregistrer le paiement puis échouer avant d’envoyer le message de confirmation. Relancer l’ensemble sans distinction risque de recréer des tâches déjà effectuées. Décomposez donc le traitement en étapes identifiables : validation du paiement, mise à jour de la commande, demande de préparation et notification. Chacune doit avoir un état observable et une règle de reprise.
Le journal technique doit aider à retrouver une commande sans accumuler inutilement des données personnelles. Une référence interne, un identifiant d’événement, un horodatage et un résultat d’étape constituent souvent des repères plus utiles qu’un gros bloc de données copié dans les logs. L’équipe support doit savoir où consulter le statut et quand solliciter un intervenant technique.
Établir une recette avec les cas qui dérangent
Testez un paiement réussi, un refus, une interruption avant le retour navigateur et une notification répétée. Ajoutez un délai entre paiement et traitement, une indisponibilité temporaire de votre serveur et une commande déjà annulée au moment où un message arrive. Le but est de vérifier les décisions commerciales, pas seulement de voir un statut HTTP positif dans un écran technique.
Pour chaque cas, écrivez le résultat attendu dans la commande, dans le paiement et dans les messages au client. Utilisez l’environnement de test correspondant à votre intégration. L’exécution doit être reproductible, avec les références de test et les observations conservées. Un scénario ne passe pas la recette si l’écran semble correct mais qu’une seconde préparation apparaît dans l’outil logistique.
Ajouter un rapprochement indépendant
Les notifications sont essentielles, mais elles ne remplacent pas une vérification des écarts. Prévoyez un rapprochement périodique entre paiements confirmés et commandes traitées. Ce contrôle doit détecter une commande restée en attente, un paiement sans référence exploitable ou une préparation déclenchée malgré un état incompatible. Il sert de filet de récupération lorsque l’intégration rencontre une interruption inattendue.
Définissez qui examine ces écarts et quelles actions sont permises. Une personne peut confirmer un rapprochement ambigu ; une autre peut autoriser un remboursement selon votre organisation. Évitez une correction automatique fondée seulement sur une somme identique. Conservez la décision et son motif pour que l’incident puisse être compris plus tard, y compris par quelqu’un qui n’a pas participé à sa résolution.
Faire du paiement une étape maintenable
Prévoyez une fiche d’incident que le support peut remplir sans accès technique étendu : référence de commande, symptôme constaté, heure approximative et action déjà tentée. Cette fiche évite les interventions concurrentes, par exemple un remboursement lancé pendant qu’une autre personne autorise la préparation. Le statut de traitement de l’incident doit être partagé avec les équipes concernées jusqu’à sa résolution.
À la livraison, demandez une carte des états, une liste des événements utilisés, une recette et une procédure de reprise. Ces documents expliquent ce qui se passe si une notification arrive tard, deux fois ou après une annulation. Ils évitent que la connaissance du paiement reste enfermée dans quelques lignes de code que personne ne sait relier à l’activité.
Notre accompagnement Stripe permet de relier le paiement aux commandes et aux outils métier. Pour cadrer votre intégration, décrivez ce qui doit se produire après une confirmation et les logiciels concernés. Nous pourrons alors définir les états, les preuves et les contrôles nécessaires avant de choisir le branchement technique.
Pour approfondir : Shopify : réussir un import CSV sans abîmer ses variantes.
Pour approfondir : Créer une boutique en ligne dans le Morbihan : préparer l’essentiel.
