Le vrai enjeu d'une intégration API Stripe n'est pas d'encaisser une carte bancaire. La douleur apparaît quand un paiement est réussi côté Stripe, qu'une commande reste bloquée côté ERP, qu'un refund part deux fois, ou qu'un litige arrive sans preuve métier exploitable par le support et la finance.
Stripe est robuste, mais il impose une discipline de run. Un PaymentIntent suit une machine d'états, les
webhooks arrivent de façon asynchrone, les retries doivent être idempotents, et les objets finance doivent rester alignés
avec les commandes, avoirs, remboursements, disputes et payouts.
Le signal faible se voit quand l'équipe commence à regarder le Dashboard Stripe pour corriger des statuts dans l'ERP, ou quand un webhook tardif contredit une correction support. Le paiement est passé, mais la source de vérité devient floue entre e-commerce, marketplace, PSP, comptabilité et back-office.
Contrairement à ce que l'on croit, l'intégration Stripe ne se joue pas seulement au checkout. Vous allez comprendre quoi conserver, quoi attendre, quoi rejouer, quoi bloquer et comment éviter qu'une réponse API correcte se transforme en dette comptable ou en double geste client.
Dawap traite Stripe comme une intégration API reliée aux flux API paiement. Notre accompagnement intégrateur Stripe aide à relier checkout, ERP, OMS, finance, support et webhooks avec une preuve de run lisible.
Pour qui Stripe devient un sujet critique
Stripe devient critique pour les e-commerces, SaaS, marketplaces, plateformes B2B, produits sur abonnement et organisations qui doivent relier l'encaissement à une commande, un compte client, une facture, un avoir ou un droit d'accès.
La priorité augmente dès que le paiement déclenche autre chose qu'un simple reçu: livraison, activation de service, provisionnement, abonnement, paiement fractionné, remboursement partiel, rapprochement comptable ou gestion de litige. Chaque action dépend alors de la bonne lecture de l'état Stripe.
Le bon signal de cadrage est simple: si un statut Stripe peut modifier la promesse client, la livraison, le cash, le support ou la comptabilité, alors le connecteur doit être conçu comme une architecture de run, pas comme un plugin de paiement que l'on surveille seulement quand une commande manque.
Les plateformes et marketplaces doivent être encore plus strictes. Dès qu'un paiement implique commission, vendeur tiers, wallet interne, compte connecté ou ventilation comptable, la moindre ambiguïté sur le statut Stripe peut se répercuter sur plusieurs parties qui n'ont pas la même lecture du cash.
1. Relier PaymentIntent, commande et état métier
Créer un PaymentIntent par commande ou session
Stripe recommande de créer un PaymentIntent pour chaque commande ou session client afin de suivre l'historique
des tentatives de paiement. Cette règle doit être traduite dans le modèle métier, pas seulement dans le code du checkout.
Le connecteur doit relier PaymentIntent, commande interne, panier, devise, montant, client, canal, tentative et
clé de corrélation. Sans cette relation, l'équipe voit un paiement dans Stripe mais ne sait pas toujours quelle décision
métier il doit produire.
La création trop tardive est un piège discret. Si le PaymentIntent n'existe qu'au dernier clic, l'entreprise perd une partie de l'historique des tentatives et ne peut pas expliquer certains abandons, refus ou bascules de méthode de paiement.
Séparer intention, tentative et charge réussie
Le PaymentIntent n'est pas une charge réussie par définition. Il guide le paiement jusqu'à son état final, avec des passages possibles par authentification, traitement asynchrone, capture manuelle ou échec. Cette nuance change tout côté ERP.
Le statut métier ne doit donc pas basculer trop vite. Une commande peut être en attente de méthode de paiement, en attente d'action client, en traitement, capturable, payée, annulée ou échouée. Ces états doivent être explicitement mappés.
Le support doit voir cette distinction. Dire "paiement Stripe créé" ne suffit pas; il faut savoir si l'argent est encaissé, seulement autorisé, encore en traitement, à reprendre ou définitivement refusé.
Conserver metadata, orderId et version de prix
Les metadata Stripe peuvent aider à retrouver commande, compte, facture ou canal. Elles ne remplacent pourtant
pas la base interne. Le SI doit conserver sa propre preuve, avec version de panier, montant attendu, devise et règle de
taxe au moment de l'intention.
Cette preuve devient indispensable lors d'un refund, d'une dispute ou d'un écart de rapprochement. Si le prix, la devise ou la taxe a changé après le paiement, l'équipe doit savoir quelle version a servi à créer le PaymentIntent.
La bonne pratique consiste à garder un journal métier autour de Stripe. Il contient l'entrée attendue, la sortie Stripe, le statut normalisé, l'identifiant Stripe, le request id, l'événement reçu et la décision appliquée au back-office.
Ce journal doit aussi enregistrer les choix de parcours. Checkout hébergé, Payment Element, paiement embarqué, paiement différé, paiement sur abonnement ou plateforme Connect ne déclenchent pas les mêmes risques de corrélation, de secret, de remboursement et de rapprochement.
2. Comprendre les statuts Stripe sans sur-réagir
Mapper requires_payment_method et requires_action
Le statut requires_payment_method indique que le paiement attend encore une méthode valable ou qu'une tentative
doit être reprise avec un autre moyen de paiement. L'ERP ne doit pas traiter cet état comme une erreur définitive si le
parcours client reste ouvert.
Le statut requires_action signale une action additionnelle, comme une authentification 3D Secure ou une étape
équivalente selon le moyen de paiement. Le connecteur doit alors informer le front ou le support sans annuler trop tôt la
commande.
Ces états protègent l'expérience client quand ils sont bien exposés. Ils créent au contraire des tickets inutiles quand le back-office les réduit à "échec paiement" sans montrer la prochaine action possible.
Respecter processing, requires_capture et succeeded
Le statut processing devient important pour les moyens de paiement asynchrones. Un paiement peut être soumis à
Stripe et rester en attente avant réussite ou échec. Le SI doit donc accepter un état intermédiaire durable.
Le statut requires_capture apparaît lorsque l'autorisation et la capture sont séparées. Dans ce cas, l'entreprise
peut avoir une autorisation valide sans encaissement final. La livraison, la réservation ou la facture doivent tenir compte
de cette différence.
Le statut succeeded permet de déclencher les suites métier, mais seulement si le connecteur a vérifié le lien
avec la commande attendue. Un paiement réussi mais mal corrélé ne doit pas libérer automatiquement une livraison ou un
abonnement.
Cette grille doit être validée avec le métier avant le go-live. Une équipe qui traite processing comme un échec
ou requires_capture comme un paiement encaissé crée des écarts difficiles à expliquer en comptabilité.
Ne pas effacer canceled et payment_failed
Un PaymentIntent annulé ou échoué porte une information utile. Il peut expliquer un abandon, un refus banque, une expiration d'autorisation, une tentative trop ancienne ou une stratégie de fraude qui a rejeté le paiement.
Le connecteur doit conserver cette trace et la traduire dans une décision claire: relancer le client, demander un autre moyen de paiement, bloquer la commande, annuler la réservation ou demander une revue humaine.
La donnée brute Stripe reste utile au diagnostic. Le support voit le statut normalisé, tandis que l'équipe technique garde le statut exact, le code d'erreur, le request id, l'événement source et la tentative associée.
Ces statuts doivent aussi être historisés, pas seulement remplacés. La chronologie d'un paiement qui passe par échec, nouvelle méthode, action client puis succès raconte une histoire utile pour le risque, la conversion et le support.
3. Webhooks signés, événements et ordre d'écriture
Vérifier la signature avant toute écriture
Les webhooks Stripe sont le cœur du run asynchrone. En production, le point d'entrée doit être exposé en HTTPS, valider la signature Stripe et préserver le corps brut nécessaire à cette vérification avant de transformer le payload.
Un événement non vérifié ne doit pas modifier une commande, un remboursement ou une facture. La vérification n'est pas un détail sécurité; c'est la condition qui permet de faire confiance au signal reçu hors parcours utilisateur.
Les secrets de signature doivent être isolés par environnement et pouvoir tourner. La rotation doit être prévue dans le runbook, parce qu'un secret compromis ou expiré ne doit pas couper toute la chaîne paiement sans mode de repli.
Le choix des événements doit être volontaire. Écouter tous les événements peut sembler rassurant, mais le run gagne en lisibilité quand les familles utiles sont nommées: PaymentIntent, charge, refund, dispute, payout, invoice ou subscription selon le périmètre réellement connecté.
Dédupliquer les événements avant de décider
Stripe peut retenter un webhook si le serveur ne répond pas correctement. Le connecteur doit donc stocker l'identifiant de l'événement, le type, l'objet relié, la date de réception et la décision appliquée avant d'écrire dans le métier.
Un même événement reçu deux fois doit produire le même résultat, pas deux refunds, deux activations ou deux emails. Cette idempotence événementielle est aussi importante que l'idempotence des appels API sortants.
La déduplication doit rester lisible. Quand le support voit qu'un événement a été ignoré, il doit comprendre qu'il était déjà traité, et non croire qu'une synchronisation a été perdue.
Écrire dans le bon ordre métier
Les événements Stripe ne doivent pas être appliqués aveuglément dans leur ordre d'arrivée. Un webhook tardif peut arriver après une relance client, une correction support, une annulation ou une mise à jour de commande.
Le connecteur doit comparer l'événement à l'état courant et décider s'il est plus récent, compatible ou à isoler. Cette règle évite de revenir en arrière sur une commande déjà corrigée ou d'écraser un état finance stabilisé.
Les files de traitement doivent séparer les familles sensibles: paiement, capture, refund, dispute, payout, abonnement et facture. Une erreur sur un flux ne doit pas bloquer toute la chaîne ni autoriser des écritures dans le mauvais domaine.
Le consommateur webhook doit répondre vite puis traiter en asynchrone. Cette séparation évite que Stripe retente inutilement pendant qu'un ERP lent écrit une facture, tout en conservant une preuve de réception avant le traitement métier.
4. Idempotence, retries et preuves de paiement
Utiliser les clés d'idempotence sur les POST
Stripe prend en charge l'idempotence sur les requêtes qui créent ou modifient des objets. Le connecteur doit fournir une clé stable pour les opérations sensibles, notamment création de PaymentIntent, capture, refund ou mise à jour critique.
Cette clé doit venir du métier, pas d'un hasard perdu dans un worker. Elle doit relier commande, action, montant, devise, type d'opération et tentative afin qu'un retry réseau ne produise pas un second effet de bord.
L'idempotence Stripe ne dispense pas de conserver une preuve locale. Le SI doit garder la clé utilisée, les paramètres envoyés, la réponse, le request id, l'heure et la décision métier qui en découle.
La clé ne doit pas être réutilisée pour une opération différente. Stripe compare les paramètres associés à une clé déjà utilisée et peut signaler une incohérence; côté métier, cette protection doit empêcher une même clé de servir à deux montants ou deux commandes.
Relire avant de rejouer
Un timeout ne prouve pas que Stripe n'a rien fait. Avant de rejouer, le connecteur doit relire le PaymentIntent, la charge, le refund ou l'objet concerné, puis comparer avec l'état attendu en interne.
Cette rellecture évite les doubles opérations et les écritures contradictoires. Un paiement peut avoir réussi alors que le serveur n'a jamais reçu la réponse; un refund peut être en cours alors que l'ERP le croit absent.
La reprise doit donc être classée: à rejouer, à attendre, à bloquer, à corriger ou à escalader. Le pire cas est un bouton "relancer Stripe" qui ne sait pas quelle opération il répète réellement.
Garder request_id et correlation_id ensemble
Stripe fournit des identifiants utiles au support technique, mais l'entreprise doit aussi garder son identifiant de corrélation métier. Les deux doivent apparaître dans les logs, les tableaux de bord et les fiches de reprise.
Cette double preuve raccourcit les incidents. Le support parle commande, client et facture; l'équipe technique retrouve l'appel Stripe, le request id, l'événement webhook et l'état exact de l'objet.
Sans cette relation, chaque incident devient une enquête entre Dashboard Stripe, logs applicatifs, ERP et exports finance. Le temps perdu se voit surtout pendant les pics de ventes ou les clôtures comptables.
Les logs doivent rester exploitables sans exposer de secret. On journalise les identifiants, statuts, montants, devises, clés métier et décisions; on évite les données sensibles inutiles, les clés API et les informations de carte qui n'ont pas leur place dans un outil support.
5. Capture, refunds, disputes et finance
Séparer autorisation et capture
Stripe permet de séparer autorisation et capture pour certains paiements. Cela convient aux paniers à vérifier, aux stocks à confirmer ou aux prestations dont le montant final peut dépendre d'une action métier.
Le connecteur doit alors suivre la fenêtre de capture, le montant capturable, les captures partielles éventuelles, la date limite et la décision qui déclenche l'encaissement. Une autorisation expirée ne doit pas être découverte après livraison.
La capture doit rester reliée à la commande et à la facture. Capturer moins, capturer plus tard ou annuler l'autorisation sont des décisions métiers qui doivent laisser une preuve finance, pas seulement un statut Stripe.
Traiter refunds et refunds partiels comme des écritures
Un refund Stripe rembourse une charge déjà créée. Il peut être total, partiel, motivé par une demande client, une fraude, un doublon ou un geste commercial. Le connecteur doit donc le relier à l'avoir, au SAV et à la comptabilité.
Le danger vient des reprises. Un refund demandé deux fois, ou demandé dans Stripe puis dans l'ERP, devient immédiatement un coût cash et un incident client. L'idempotence doit couvrir l'opération autant que le webhook de confirmation.
Chaque refund doit exposer son montant, sa devise, sa raison, sa commande, son avoir, son initiateur, son statut Stripe et sa trace de rapprochement. Sans cela, la finance corrige dans un tableur ce que le connecteur aurait dû expliquer.
Ne pas traiter disputes comme de simples notifications
Une dispute Stripe touche le paiement, la preuve de livraison, le dossier client, la fraude, le SAV et parfois la finance. Elle ne doit pas rester une notification lue dans un Dashboard par une seule personne.
Le connecteur doit créer un dossier métier avec identifiant Stripe, charge, commande, preuves disponibles, délai de réponse, owner et statut. Les webhooks de dispute doivent alimenter ce dossier sans écraser les actions déjà engagées.
Cette approche évite les pertes sèches. La qualité du dossier de preuve, le délai de réponse et le lien avec la commande comptent autant que le statut technique reçu depuis Stripe.
Rapprocher payouts, frais et balance transactions
Le cash réellement reçu ne se lit pas seulement sur le PaymentIntent. Les frais, balance transactions, payouts, refunds et disputes expliquent le passage entre montant client, montant net, versement bancaire et écriture comptable.
Le connecteur doit relier ces objets à la bonne période, à la devise, au compte Stripe, au canal et au dossier finance. Sinon, la comptabilité voit un versement agrégé sans pouvoir relier facilement les ventes, remboursements et frais associés.
Cette étape doit être prévue dès le cadrage. Attendre la clôture pour découvrir que les identifiants finance sont absents transforme un succès checkout en dette de rapprochement.
Le support doit aussi savoir si un client parle du paiement initial, du remboursement, du versement bancaire ou d'un frais Stripe. Ces sujets se ressemblent côté client, mais ils n'ont pas le même owner ni la même preuve.
6. Erreurs fréquentes dans une intégration Stripe
Confondre paiement réussi et commande livrable
La première erreur fréquente consiste à déclencher toute la chaîne métier dès que Stripe indique un succès, sans vérifier le montant, la devise, la commande, le canal, le risque, le stock ou les règles de capture.
Un paiement réussi mais mal corrélé ne doit pas libérer une livraison. Il doit passer en quarantaine avec une preuve Stripe, une commande candidate et une action support, car le coût d'une activation erronée dépasse souvent le coût d'un contrôle.
Cette prudence est encore plus importante en marketplace ou SaaS. Le paiement peut ouvrir un droit, déclencher une commission, lancer une facture ou répartir un montant entre plusieurs parties.
Se fier au polling plutôt qu'aux webhooks
Le polling peut aider ponctuellement, mais Stripe recommande les webhooks pour suivre les paiements dont la confirmation est retardée ou asynchrone. Un polling permanent risque de manquer l'ordre métier et de consommer inutilement les limites API.
La bonne architecture reçoit les événements, les vérifie, les met en file, les déduplique et relit Stripe seulement quand l'état local est incertain. Le polling devient un outil de reprise, pas la source principale de vérité.
Cette règle réduit le bruit. L'équipe ne passe plus son temps à demander "où en est Stripe"; elle sait quel événement a été reçu, quel objet a été relu et quelle décision a été appliquée.
Le polling de secours doit être limité à des cas nommés: webhook absent, incident réseau, état interne incohérent ou contrôle de rapprochement. S'il devient permanent, il masque probablement un problème de traitement événementiel.
Oublier les flux finance autour du paiement
Une intégration Stripe trop centrée sur le checkout oublie les frais, payouts, balance transactions, refunds, disputes, factures, avoirs et rapprochements. Le paiement semble marcher, mais la clôture devient manuelle.
Le connecteur doit prévoir le vocabulaire finance dès le départ. Un PaymentIntent ne suffit pas à expliquer un montant net, un frais, un remboursement partiel ou une écriture de rapprochement dans l'ERP.
Cette erreur coûte cher parce qu'elle arrive tard. Les ventes sont déjà passées, les clients sont livrés, puis la finance découvre que les identifiants ou les dates ne permettent pas de rapprocher proprement.
7. Scénario terrain: payé côté Stripe, bloqué côté ERP
Le checkout fonctionne, mais l'ERP n'avance pas
Imaginons une boutique qui passe sur Stripe avec PaymentIntents et webhooks. Le checkout encaisse correctement, mais une partie des commandes reste bloquée en attente de paiement dans l'ERP après un pic de trafic.
Au départ, le tableau de bord Stripe rassure: les paiements ont réussi. Le signal faible apparaît quand le support traite toujours les mêmes demandes, alors que les clients ont une preuve bancaire mais aucune confirmation de commande exploitable.
Le problème ne vient pas forcément de Stripe. Il vient souvent d'un webhook rejeté, d'un événement reçu deux fois, d'un ordre d'écriture fragile ou d'une corrélation insuffisante entre PaymentIntent, commande interne et tentative de paiement.
La correction commence par la chronologie
La première correction consiste à reconstruire la chronologie: création du PaymentIntent, confirmation, action client, webhook reçu, relance éventuelle, écriture ERP, email client et rapprochement finance.
La deuxième correction consiste à séparer les états. Un paiement peut être réussi dans Stripe, mais non appliqué dans l'ERP; il faut alors isoler le dossier et appliquer une reprise ciblée au lieu de modifier la commande à la main.
La troisième correction consiste à rendre la preuve visible. Le support doit voir le PaymentIntent, le statut Stripe, le dernier webhook traité, l'écriture ERP, la prochaine action autorisée et les actions interdites.
Le résultat attendu se mesure à la reprise
Après correction, l'équipe ne cherche plus dans Stripe à chaque ticket. Elle sait quels paiements sont en quarantaine, quels événements ont été dédupliqués, quelles commandes peuvent être relancées et quelles écritures finance doivent attendre.
Le support gagne en autonomie, la finance gagne en traçabilité et le produit peut élargir les moyens de paiement sans ajouter une couche de risque invisible. Le connecteur devient un outil de décision, pas seulement un tuyau API.
Ce scénario résume l'enjeu Stripe. L'encaissement peut être excellent et le run fragile si le SI ne sait pas expliquer ce qui a été payé, appliqué, remboursé, contesté ou rapproché.
8. Plan d'action avant go-live Stripe
Cadrer les objets et les sources de vérité
La première étape consiste à lister les objets: commande, client, PaymentIntent, charge, capture, refund, dispute, payout, facture, avoir, abonnement éventuel, webhook, request id et écriture ERP. Chaque objet doit avoir un owner.
La deuxième étape consiste à écrire la source de vérité par décision. Stripe peut faire foi pour le paiement, l'ERP pour la facture, l'OMS pour la livraison, la finance pour le rapprochement et le support pour la décision client.
La troisième étape consiste à figer les états normalisés. Le back-office n'a pas besoin de tous les détails Stripe, mais il doit comprendre ce qui est à attendre, à relancer, à bloquer, à rembourser, à contester ou à rapprocher.
Installer les garde-fous techniques
Les garde-fous couvrent clés API, rotation des secrets, signature webhook, idempotence des POST, déduplication des events, queue, backoff, logs corrélés, stockage minimal, séparation des environnements et accès support.
Les appels sensibles doivent être regroupés par domaine: création et confirmation de PaymentIntent, capture, refund, dispute, rapprochement finance et notification client. Chaque domaine reçoit ses propres règles de retry, rollback et quarantaine.
Le lot technique doit définir les entrées, les sorties, les responsabilités, la journalisation, l'idempotence, le monitoring, la file de reprise, les seuils d'escalade et le runbook de repli. Ces éléments évitent la correction improvisée.
Préparer la bascule et le mode contrôlé
Le lancement doit commencer sur un périmètre maîtrisé: un canal, une devise, un moyen de paiement principal, un mode de capture et une famille de refunds. Cette limitation donne assez de signal sans exposer tout le cash.
Le mode contrôlé doit permettre de fermer un moyen de paiement, suspendre les captures manuelles, isoler les refunds, conserver les webhooks entrants ou bloquer les activations client sans couper tout Stripe.
Les dépendances doivent être nommées avant la bascule: front checkout, backend commande, queue, worker webhook, ERP, outil support, module facture, export comptable et accès au Dashboard Stripe. Sans cette carte, la reprise dépendra de la mémoire de l'équipe présente le jour de l'incident.
- D'abord, à valider: un PaymentIntent par commande, webhook signé, event dédupliqué, refund corrélé, dispute visible et rapprochement finance testable.
- Ensuite, à bloquer: succès Stripe sans commande interne, refund sans avoir, capture sans statut capturable et webhook non signé qui tente une écriture.
- Puis, à corriger: metadata ambiguë, idempotency key absente, polling trop agressif, statut ERP trop pauvre et dashboard support sans request id.
- Enfin, à différer: nouveaux moyens de paiement, pays ou flux Connect dont le runbook ne sait pas encore expliquer captures, refunds et disputes.
Un bon go-live Stripe ne cherche pas à activer toute la richesse du PSP d'un coup. Il cherche à prouver que paiement, capture, webhook, refund, dispute et finance restent lisibles quand les premiers incidents réels apparaissent.
9. Recette, seuils et observabilité Stripe
Tester les cas qui coûtent vraiment
La recette doit couvrir paiement réussi, paiement échoué, requires_action, processing, capture
manuelle, annulation, refund total, refund partiel, dispute, webhook rejoué, webhook tardif et timeout après POST.
Chaque scénario doit préciser l'état attendu dans le checkout, l'ERP, l'OMS, la finance et le support. Le test est réussi quand ces systèmes racontent la même décision, même si le statut brut vient de Stripe.
Les preuves attendues doivent être conservées pendant la recette: payload, response, request id, event id, signature validée, statut normalisé, écriture métier, owner de reprise et action interdite. Sans ce dossier, le run reste fragile.
Rejouer la recette après chaque changement
La recette doit aussi tester les erreurs volontaires: signature webhook invalide, double event, idempotency key réutilisée, devise incohérente, refund supérieur au montant autorisé, capture trop tardive et dispute sans preuve de commande.
Les scénarios de recette doivent être rejoués après chaque changement de moyen de paiement, règle de capture, pays, devise ou module comptable. Une intégration Stripe peut être correcte sur carte simple et devenir fragile dès que le parcours ajoute un moyen asynchrone ou une ventilation finance plus fine.
Cette reprise de recette doit produire une preuve comparable à la première validation: mêmes cas, mêmes états attendus, mêmes owners et mêmes interdits. Si la comparaison n'est pas possible, le changement est trop risqué pour être ouvert sur tout le trafic.
Fixer des seuils actionnables
Les seuils doivent décider le mode de run. Par exemple, si pendant 2 jours des paiements réussis restent non appliqués dans l'ERP, alors l'élargissement est à bloquer, car le cash, la livraison et la charge support sont déjà exposés.
Cas concret: si un délai de rapprochement refund dépasse 1 jour sur un canal prioritaire, alors les nouveaux moyens de paiement sont à différer, car la finance et le SAV n'ont pas encore la preuve nécessaire pour absorber plus de volume.
Les seuils doivent distinguer incident isolé et dérive. Un webhook rejeté peut se corriger; une famille d'événements sans corrélation signale une rupture plus profonde du mapping, de l'idempotence ou de la file de traitement.
Rendre la passation support autonome
Une intégration Stripe devient durable quand le support peut comprendre un cas sans demander au développement. Il doit voir le PaymentIntent, le statut normalisé, le dernier webhook, le request id, le refund, la dispute et l'action autorisée.
La fiche support doit couvrir les cas simples: paiement en attente d'action, paiement processing, succès non appliqué, refund en cours, dispute ouverte, webhook ignoré, capture expirée, erreur de devise et écart de rapprochement.
La passation doit aussi indiquer les interdits: rembourser deux fois, capturer sans vérifier l'état, livrer sur paiement non corrélé, écraser un statut plus récent ou répondre à une dispute sans preuve reliée à la commande.
Les 30 premiers jours doivent être relus avec support et finance. Si les mêmes questions reviennent sur PaymentIntent, refund, dispute, payout ou webhook, il faut enrichir la preuve visible avant d'ajouter des pays, moyens de paiement ou scénarios Connect.
Questions fréquentes sur Stripe
Pourquoi un PaymentIntent doit-il rester lié à la commande métier ? Stripe recommande un PaymentIntent par commande ou session client. Le SI doit donc relier cet objet à la commande, aux tentatives, aux webhooks, aux refunds et aux écritures finance.
Comment éviter les doubles paiements ou doubles remboursements avec Stripe ? Il faut utiliser des clés d'idempotence sur les POST, relire les objets avant retry, dédupliquer les webhooks et isoler les cas incertains en quarantaine avant toute écriture métier.
Dawap peut-il accompagner une intégration Stripe API ? Oui. Dawap accompagne le cadrage Stripe, les PaymentIntents, webhooks, captures, refunds, disputes, mappings ERP/e-commerce, rapprochements finance, reprises, recette et observabilité de production.
Guides complémentaires pour Stripe
Une intégration Stripe touche rarement le checkout seulement. Les ressources suivantes aident à approfondir la chaîne paiement, la maîtrise des doublons, la réception d'événements et le rapprochement entre systèmes.
Architecture paiement de bout en bout
La lecture paiement API replace Stripe dans une chaîne complète: autorisation, capture, refund, litige, paiement net, écriture finance et preuve opérationnelle entre les systèmes métier.
Elle aide à décider ce qui appartient au checkout, au PSP, au middleware, à l'ERP ou à la comptabilité. Cette frontière évite les corrections tardives quand un paiement réussi ne correspond pas à une commande exploitable.
Elle donne aussi une grille pour relire les exceptions: paiement asynchrone, capture manuelle, remboursement partiel, contestation, payout ou écart entre montant encaissé et montant rapproché.
Protection contre les doubles traitements
La ressource idempotence API et doublons métier donne le cadre nécessaire pour éviter les PaymentIntents recréés, les captures répétées, les refunds en double et les webhooks rejoués sans contrôle.
Elle devient prioritaire dès qu'un timeout peut masquer une opération réussie, qu'un opérateur peut relancer une commande ou qu'un événement peut revenir après une correction support. Le coût d'un doublon de paiement dépasse souvent celui d'une validation stricte.
Elle donne enfin une méthode pour relier clé métier, journalisation, queue, retry, rollback et preuve support. Cette méthode s'applique directement aux flux Stripe les plus sensibles.
Webhooks et lectures contrôlées
La ressource webhook ou polling API permet de choisir une stratégie fiable pour les événements Stripe, les relances, les lectures contrôlées et les reprises.
Elle aide à décider quand accepter un webhook, quand le rejouer, quand le mettre en quarantaine et quand compléter par une rellecture du PaymentIntent. Cette décision devient centrale quand les paiements sont asynchrones.
Elle évite aussi de confondre temps réel et vérité métier. Un événement rapide peut être faux pour le SI si la chronologie, la clé de corrélation et l'état courant ne sont pas vérifiés avant écriture.
Réconciliation entre Stripe et l'ERP
La ressource réconciliation API prolonge les questions d'écart entre Stripe, e-commerce, ERP et comptabilité, surtout lorsque refunds, fees, payouts et disputes entrent dans le périmètre.
Elle devient utile quand le volume empêche de traiter les écarts à la main. La méthode consiste à rapprocher identifiants, montants, dates, statuts, devises et décisions avant d'ouvrir un incident.
Cette lecture convient aux équipes qui veulent passer de la correction manuelle au pilotage. L'écart n'est plus seulement une anomalie; il devient un objet de run avec cause, owner, seuil et prochaine action.
Runbook quand Stripe bloque une commande
La ressource runbook d'incident API complète ce parcours quand un PaymentIntent est réussi côté Stripe mais qu'une commande reste bloquée côté ERP, OMS ou support. Elle aide à décider quoi geler, quoi rejouer et quoi escalader sans transformer un incident paiement en reprise large sur toute la journée.
Elle sert aussi à formaliser les seuils utiles: backlog de webhooks, captures en attente, refunds ambigus, disputes sans preuve ou écart entre payout et écriture finance. Pour Stripe, cette grille rend le diagnostic reproductible au lieu de dépendre du réflexe de la personne de garde.
Conclusion: intégrer Stripe sans boîte noire
Une intégration API Stripe réussie ne se mesure pas au premier paiement accepté. Elle se mesure à la capacité d'expliquer un PaymentIntent, un webhook, une capture, un refund, une dispute ou un écart finance sans reconstruire toute la chaîne.
Le bon ordre reste stable: relier la commande au PaymentIntent, mapper les statuts, vérifier les webhooks, rendre les POST idempotents, protéger les refunds, traiter les disputes et donner au support une preuve lisible.
Cette discipline ne ralentit pas le projet. Elle évite que Stripe devienne une boîte noire cash, réduit les doubles gestes, protège la marge et rend l'élargissement vers de nouveaux moyens de paiement beaucoup plus maîtrisable.
Si vous devez connecter Stripe à un ERP, un OMS, une marketplace, un SaaS ou une boutique avec une preuve de run solide, notre accompagnement en intégration API peut cadrer l'architecture, les mappings, les reprises et l'observabilité sans déplacer la dette vers le support ou la finance.
