Ressources · 47
Paiement incertain : reprendre le parcours sans commande en double
Traiter délai réseau, retour navigateur, notifications et état métier comme des signaux à rapprocher.
· 5 min
Ce que ce guide permet
- Distinguer tentative, paiement et commande
- Gérer les retours retardés ou absents
- Dédupliquer notifications et demandes
- Expliquer l’incertitude sans faire repayer
Contrôle express
- Quelle source confirme le paiement ?
- La fermeture du navigateur change-t-elle l’état métier ?
- Une notification répétée prépare-t-elle deux commandes ?
- Les signatures des événements sont-elles vérifiées ?
- Comment le support retrouve-t-il une opération incertaine ?
Méthode pas à pas
- 01
Définir les états
Séparez panier, tentative, autorisation, paiement confirmé, commande et remboursement. Écrivez transitions, source faisant foi et actions permises. Le modèle doit suivre le fournisseur et les moyens de paiement réellement utilisés ; tous ne confirment pas immédiatement.
Livrable : diagramme d’états et contrat métier.
- 02
Identifier l’opération
Reliez une tentative à une commande et aux identifiants du fournisseur. Utilisez la règle d’idempotence documentée pour une répétition de la même opération. Un nouveau besoin ou des paramètres différents nécessitent une décision explicite, pas la réutilisation aveugle d’une clé.
Livrable : identité stable et règles de reprise.
- 03
Traiter le retour navigateur
Affichez l’état obtenu par une vérification serveur adaptée au fournisseur. N’utilisez pas le seul retour vers une page de succès comme preuve de paiement. Prévoyez navigateur fermé, retour absent, authentification interrompue et réseau lent.
Livrable : parcours de retour et messages par état.
- 04
Vérifier les notifications
Vérifiez authenticité selon la documentation du fournisseur, enregistrez l’identifiant d’événement et traitez les répétitions sans effet doublé. Les événements peuvent arriver tard ou dans un autre ordre. Si nécessaire, relisez l’objet de référence avant une transition irréversible.
Livrable : gestionnaire testé et traces sans données bancaires.
- 05
Rapprocher les écarts
Comparez opérations du fournisseur, commandes et préparation. Isolez les cas payé sans commande, commande sans confirmation, double traitement et remboursement non propagé. Donnez à chaque écart un propriétaire et une procédure ; ne relancez pas automatiquement un débit incertain.
Livrable : file de rapprochement et décisions.
- 06
Tester la reprise complète
Dans le mode de test du fournisseur, rejouez timeout, doublon, événement retardé, ordre inversé et retour absent. Vérifiez une seule transition métier, la bonne information au client et la visibilité au support. Les détails d’idempotence diffèrent entre fournisseurs.
Livrable : preuves de non-duplication et critères de mise en service.
Cas de recette proposés
Scénarios fictifs à adapter dans un environnement autorisé. Ils ne décrivent aucun résultat client ni une certification.
| Situation fictive | Contrôle proposé | Preuve à conserver |
|---|---|---|
| Le client reçoit un timeout après une demande alors que son résultat est incertain. | Retrouver l’opération existante et son état auprès de la source prévue avant une nouvelle tentative. Distinguer clé d’idempotence, référence de commande et état métier. | Chronologie et identifiants techniques non sensibles, état observé et règle de reprise applicable à l’API concernée. |
| Une notification valide est reçue deux fois ou après une notification plus récente. | Tester la signature puis la déduplication et l’ordre métier. Une livraison répétée ne doit pas déclencher une seconde préparation ou une seconde confirmation client. | Identifiant de notification, transition acceptée ou ignorée et preuve d’un effet métier unique. |
Exemple d’application
Situation illustrative
Situation illustrative : le paiement réussit, mais la connexion du client coupe avant la page de confirmation et deux notifications arrivent ensuite.
Décision et preuve attendue
Une seule commande est confirmée. La reprise affiche son état vérifié ; le support peut rapprocher la référence sans demander les données bancaires.
Distinguer les mécanismes
| Mécanisme | Utilité | Point de vigilance |
|---|---|---|
| Retour navigateur | Informer et reprendre l’interface | Peut être absent ou interrompu |
| Webhook vérifié | Recevoir un changement du fournisseur | Peut être répété, retardé ou désordonné |
| Rapprochement serveur | Comparer état du paiement et commande | Nécessite une règle de résolution des écarts |
Indicateurs de pilotage
| Indicateur | Ce qu’il mesure | Première action |
|---|---|---|
| États incertains | Opérations non résolues dans le délai prévu | Vérifier l’état de référence |
| Effets dupliqués | Commandes ou traitements en double | Corriger la déduplication métier |
| Écarts clos | Cas rapprochés avec décision et preuve | Traiter les plus anciens et critiques |
Erreurs fréquentes
- Confirmer depuis une URL de succès seule
- Transformer un timeout en paiement échoué
- Supposer que les événements arrivent dans l’ordre
- Recommencer un débit avant vérification
Questions fréquentes
Un timeout signifie-t-il un échec ?
Non. Il signifie que la réponse n’a pas été reçue dans le délai. Vérifiez l’état de l’opération avant d’en créer une nouvelle.
L’idempotence du fournisseur suffit-elle ?
Non. Votre création de commande, préparation et notification doivent aussi supporter un traitement répété sans effet métier doublé.
Que dire à l’utilisateur ?
Expliquez que la vérification est en cours, donnez une référence sûre et un moyen de retrouver l’état. Évitez une demande de nouveau paiement tant que le précédent reste incertain.
Quelle preuve conserver pour une vérification utile ?
Conservez des identifiants techniques non sensibles, les états successifs et la preuve d’un effet métier unique. Reliez la reprise au contrat de l’API utilisée ; un timeout ou une notification isolée ne décrit pas forcément l’état final de la commande.
Webhooks : signatures et rejeu
Une notification de paiement ne suffit pas à clore le rapprochement
Authentifiez chaque webhook, reliez-le au bon compte et comparez son effet à l’état serveur autorisé. Un événement répété ne doit pas répéter une activation initiale ; un événement absent doit rester détectable.
- Distinguer identifiant de notification et identité de l’opération à réaliser.
- Tester renvoi manuel et retry automatique concurrents.
- Conserver un état incertain après résultat externe inconnu et vérifier la source avant relance.
Voir les signatures, les empreintes et les dix cas webhooks →
Sources vérifiées le · Stripe · Webhooks · Stripe · Manage webhook endpoints · GitHub · Validating webhook deliveries · GitHub · Best practices for using webhooks · GitHub · Handling failed webhook deliveries
Précision des montants API et unités exactes
Séparer conversion exacte et confirmation du paiement
Une interface peut afficher le bon prix tout en préparant un entier incorrect pour le prestataire. La recette doit rapprocher le montant serveur avec le contrat de l’opération, puis vérifier l’état confirmé sans confondre le calcul avec un paiement abouti.
- Tester une monnaie à zéro, deux et trois décimales.
- Inclure une exception où le pas ne se déduit pas des décimales.
- Conserver une valeur de référence exacte avant le formatage localisé.
Vérifier une unité dans l’atelier →
Adyen · Currency codes and minor units · Provider documentation · reviewed 2026-11-06
Stripe · Supported currencies and special cases · Provider documentation · reviewed 2026-11-06
Références officielles
Date de consultation des références : . La méthode et la fiche de travail proposent des contrôles à adapter à votre contexte ; elles ne constituent pas une certification.
- Stripe — Payment status updates
- Stripe — Webhooks
- Stripe — Idempotent requests
- Stripe · Manage webhook endpoints
- GitHub · Validating webhook deliveries
- GitHub · Best practices for using webhooks
- GitHub · Handling failed webhook deliveries
- Adyen · Currency codes and minor units
- Stripe · Supported currencies and special cases
