Webhooks et abonnements Stripe : ce que les applications créées par l'IA font de travers

Les paiements sont l’endroit où le code généré par IA paraît terminé avant de l’être vraiment. La page de paiement s’ouvre, la carte de test fonctionne, un écran « Merci » s’affiche, et tout semble fini. Pourtant, encaisser le premier paiement est la partie facile de la facturation. Le vrai travail, c’est tout ce qui se passe ensuite : renouvellements, cartes refusées, résiliations, changements de forfait, remboursements, nouvelles tentatives et messages en double.

Ce guide présente les erreurs Stripe que nous chercherions en priorité dans une application créée par IA, pourquoi chacune coûte de l’argent ou de la confiance, et comment la corriger. Si vous souhaitez une vision plus large avant le lancement, commencez par notre checklist de préparation à la production.

Le modèle mental : Stripe est la source de vérité

Le statut de facturation de votre client réside dans Stripe. Votre propre base de données en conserve une copie, et les webhooks sont le moyen par lequel Stripe informe votre application d’un changement. Un webhook, c’est simplement Stripe qui envoie une requête HTTP à une URL de votre serveur : « ce paiement a réussi », « cet abonnement a été résilié », « cette facture a échoué ».

La plupart des bugs de facturation viennent d’une entorse à ce modèle : faire confiance au navigateur plutôt qu’à Stripe, faire confiance à des messages sans vérifier leur expéditeur, ou supposer que chaque message arrive exactement une fois et dans l’ordre. Aucune de ces hypothèses ne tient.

Erreur n° 1 : accorder l’accès depuis la page de succès

Un schéma courant dans le code généré par IA redirige vers /success après le paiement et déverrouille le produit sur cette page. Mais la redirection n’est qu’une navigation du navigateur. Un client peut fermer l’onglet avant son chargement et ne jamais obtenir d’accès, et n’importe qui peut saisir l’URL de succès à la main et obtenir l’accès sans payer.

Correctif : ne déverrouillez l’accès que lorsque votre serveur a reçu et vérifié l’événement Stripe correspondant, puis lisez l’accès de l’utilisateur dans votre base de données. La page de succès peut afficher un message rassurant du type « nous confirmons votre paiement » pendant que le webhook arrive.

Erreur n° 2 : ne pas vérifier la signature du webhook

L’URL de votre webhook n’est qu’une adresse publique. Si le gestionnaire accepte n’importe quelle requête, n’importe qui peut envoyer un faux événement « paiement réussi » pour son propre compte. Stripe signe chaque événement, et votre serveur doit vérifier cette signature à l’aide du secret de signature du endpoint.

La vérification nécessite le corps brut de la requête. Si un framework analyse d’abord le corps en JSON et que vous vérifiez la version re-sérialisée, la vérification échoue, et les outils d’IA « règlent » parfois ce problème en désactivant la vérification. Voici à quoi ressemble un gestionnaire correct dans une route Next.js :

export async function POST(req) {
  const body = await req.text();            // raw body, not req.json()
  const sig = req.headers.get("stripe-signature");

  let event;
  try {
    event = stripe.webhooks.constructEvent(
      body, sig, process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    return new Response("Invalid signature", { status: 400 });
  }

  // ...handle the event, then acknowledge it quickly
  return new Response("ok", { status: 200 });
}

Dans Express, utilisez l’analyseur de corps brut pour cette seule route. Une erreur de signature qui n’apparaît qu’en production signifie généralement que le secret de signature est incorrect : les endpoints de test et de production ont chacun le leur.

Erreur n° 3 : supposer une seule livraison, dans l’ordre

Stripe livre les événements au moins une fois ; le même événement peut donc arriver deux fois, et les événements peuvent arriver dans le désordre. Si votre gestionnaire ajoute des crédits ou crée une commande chaque fois qu’il voit un événement, une nouvelle tentative le fera deux fois.

Correctif : stockez l’ID de chaque événement traité et ignorez les doublons. Faites en sorte que les gestionnaires définissent un état (par exemple « le statut est actif jusqu’à cette date ») au lieu d’incrémenter des compteurs, afin que les répéter soit sans conséquence. Lorsque l’ordre compte, récupérez l’objet actuel depuis Stripe plutôt que de vous fier à l’ordre d’arrivée des messages.

Erreur n° 4 : ne gérer que le premier paiement

Un abonnement a un cycle de vie, et chaque étape exige une décision dans votre application. Voici les événements que la plupart des produits doivent gérer :

Votre liste exacte dépend de votre modèle tarifaire, mais « nous ne gérons que le paiement initial » n’est presque jamais suffisant.

Erreur n° 5 : traiter la résiliation comme immédiate

Lorsqu’un client résilie, la plupart des entreprises lui laissent l’accès jusqu’à la fin de la période déjà payée. Stripe représente cela par un indicateur sur l’abonnement précisant qu’il sera résilié à la fin de la période. Les applications qui retirent l’accès immédiatement provoquent des demandes de remboursement et des plaintes, et celles qui ignorent l’indicateur continuent de servir des clients qui sont partis.

Montrez au client l’état réel dans votre interface (« Votre forfait se termine le 14 mars »), et envisagez le portail client hébergé de Stripe pour les changements de forfait et les résiliations afin de ne pas avoir à construire ces écrans.

Erreur n° 6 : aucun plan pour les paiements échoués

Les cartes expirent, les banques refusent, les plafonds sont atteints. Un renouvellement échoué est normal, et un abonnement en retard de paiement n’est pas encore un client perdu. Décidez de votre politique à l’avance : quelle est la durée du délai de grâce, que voit le client et quels e-mails sont envoyés. Stripe peut relancer automatiquement les prélèvements échoués et envoyer des e-mails de rappel, mais votre application doit tout de même réagir de façon cohérente aux changements de statut.

Erreur n° 7 : mélanger les modes test et production

Le mode test et le mode production sont deux mondes distincts, avec leurs propres clés, produits, prix, clients et endpoints de webhook. Les erreurs typiques incluent un site en production utilisant une clé secrète de test, un endpoint de webhook de production qui n’a jamais été créé, ou un ID de prix copié depuis le mauvais mode. Conservez les clés de chaque mode dans des variables d’environnement distinctes pour chaque environnement, et ne laissez jamais un jeu de clés se glisser dans l’autre.

Pour bien tester, utilisez la Stripe CLI pour transférer les événements vers votre machine locale et déclencher des événements d’exemple, et utilisez les test clocks de Stripe pour simuler en quelques minutes des mois de renouvellements, d’échecs et de résiliations.

Erreur n° 8 : effectuer le gros du travail dans le webhook

Stripe attend une réponse rapide. Si votre gestionnaire envoie des e-mails, appelle d’autres services et met à jour de nombreuses tables avant de répondre, il risque d’expirer et Stripe considérera la livraison comme échouée. En mode production, Stripe réessaie les livraisons échouées avec des délais croissants pendant trois jours au maximum, ce qui multiplie les traitements en double si le gestionnaire n’est pas idempotent. Accusez réception rapidement et confiez le travail lent à une tâche en arrière-plan.

Une courte revue de facturation à faire dès aujourd’hui

1. La signature du webhook est-elle vérifiée à partir du corps brut ?
2. Les ID des événements traités sont-ils stockés pour que les doublons soient ignorés ?
3. L’accès dépend-il du statut d’abonnement dans votre base de données, et non de la page de succès ?
4. Avez-vous testé en mode test un paiement échoué, une résiliation, un changement de forfait à la hausse et un remboursement ?
5. Le mode test et le mode production utilisent-ils des clés, des secrets et des endpoints différents ?
6. Pouvez-vous trouver, en une minute, pourquoi un client donné a ou n’a pas accès ?

Si plusieurs réponses sont « je ne sais pas », la facturation est probablement la partie de votre application à examiner en premier. Notre audit technique d’application IA inclut dans son périmètre les flux de paiement et la gestion des webhooks, et la réparation et mise en production d’applications IA couvre la finalisation ou la correction du paiement Stripe, des mises à jour d’abonnement, des résiliations et des webhooks, avec des tests pour chaque flux.