Bugs de contrôle de facturation : corriger les vérifications de plan et les failles de webhook

À quoi ressemblent les bogues de contrôle de facturation en vraie vie

Les bogues de contrôle de facturation apparaissent quand votre page de tarification dit une chose mais que le produit se comporte autrement. Un utilisateur sur le plan Free clique sur un bouton et tout à coup il peut exporter, inviter des coéquipiers ou consommer des crédits IA premium sans payer.

Le premier signe, c’est l’incohérence. Un client est bloqué, un autre avec le même plan ne l’est pas. L’accès change après un rafraîchissement, une déconnexion ou une tentative d’upgrade. Les tickets support ressemblent à : « Ça marchait hier », « Mon collègue peut le faire mais pas moi », ou « J’ai fait l’upgrade mais ça dit encore que je suis verrouillé. »

Les prototypes sont particulièrement vulnérables parce qu’ils sautent souvent les garde-fous ennuyeux. La première version peut se reposer sur un bouton caché, une vérification côté front, ou un simple drapeau plan dans la table utilisateur. Ça peut sembler OK en démo, puis se casser dès que la facturation réelle, les webhooks et de vrais utilisateurs arrivent.

Appliquer les règles, c’est répondre à quatre questions à chaque fois qu’une action de valeur est demandée :

• Qui est l’utilisateur, et à quel compte/workspace appartient-il ?
• Quel plan et quels add-ons sont actifs maintenant ?
• Quelle action exacte essaie-t-il d’exécuter ?
• Le serveur doit-il l’autoriser (pas seulement l’UI) ?

Quand ces réponses sont floues, ou dispersées, des bogues apparaissent. Un exemple classique : quelqu’un ajoute un nouvel endpoint « Pro-only », mais oublie d’ajouter la même vérification à un job en arrière-plan qui l’appelle. L’UI cache toujours la fonctionnalité, mais l’endpoint reste atteignable directement ou indirectement.

Si vous avez hérité d’un prototype SaaS généré par IA (Lovable, Bolt, v0, Cursor, Replit), ces lacunes sont courantes. FixMyMess trouve souvent des vérifications de plan manquantes sur un ou deux chemins critiques, plus au moins un endroit où l’état de facturation est supposé au lieu d’être vérifié. C’est souvent suffisant pour que des fonctionnalités payantes deviennent gratuites sans le dire.

Cartographiez les endroits où l’accès doit être appliqué

La plupart des bogues de contrôle de facturation viennent du fait qu’on vérifie l’accès à un endroit puis on l’oublie au suivant. Le moyen le plus rapide d’empêcher l’accès gratuit aux fonctionnalités payantes est de lister chaque « action payante » qu’un utilisateur peut déclencher et de s’assurer que chaque chemin passe par la même règle.

Commencez par les actions payantes en langage utilisateur : « exporter CSV », « inviter un coéquipier », « lancer le rapport », « retirer le watermark ». Puis traduisez chacune en chemins d’exécution réels : la route API, tout job en arrière-plan qu’elle queue, et tout chemin UI (y compris les boutons cachés) qui peut encore appeler l’API.

Mettez les vérifications côté serveur en priorité. L’UI peut cacher des boutons, mais on ne peut pas lui faire confiance. Si un endpoint peut être appelé, il doit valider les droits à chaque fois.

Systèmes à inclure dans votre carte

Notez chaque système qui touche aux entitlements, même si le code est en bazar :

• Base de données de l’app (utilisateur, org/workspace, tables d’abonnement ou d’entitlement)
• Couche d’auth (sessions, claims JWT, rôles)
• Fournisseur de facturation (plans, subscriptions, invoices)
• Webhooks et traitement d’événements (y compris retries et délais)
• Caches/queues (tout ce qui peut servir un accès obsolète)

Une fois que vous voyez le tableau complet, choisissez une source de vérité pour les entitlements et tenez-vous y. Pour la plupart des apps SaaS, c’est un enregistrement d’entitlement dans votre propre base qui représente « ce que ce workspace peut faire maintenant », mis à jour par les webhooks et vérifié sur les actions importantes.

Une erreur de prototype courante : des vérifications de plan éparpillées dans le frontend, quelques routes API et un handler webhook. Le résultat, c’est un accès incohérent et des fuites difficiles à reproduire. Un modèle d’entitlement unique plus une garde partagée côté serveur comblent la plupart des trous rapidement.

Étapes : corriger les vérifications de plan pour que les fonctionnalités payantes restent verrouillées

La rupture du contrôle de facturation survient quand les règles sont dispersées. Un endpoint vérifie le plan, un autre se fie à un drapeau UI, et un troisième n’en vérifie rien du tout. La correction est simple : centraliser la décision et la réutiliser partout.

1) Trouvez tous les endroits pouvant déclencher une action payante

Faites l’inventaire des routes serveur et des jobs en arrière-plan qui font quelque chose de précieux : exporter des données, inviter des coéquipiers, lever des limites, générer des rapports, utiliser des appels IA premium, et les actions admin. Si ça modifie des données ou ça vous coûte de l’argent, il faut une porte.

Ensuite, ajoutez une garde unique à un endroit que toutes les routes payantes utilisent. Ne réécrivez pas des vérifications dans chaque handler.

2) Déplacez toutes les décisions d’accès côté serveur

Traitez tout ce qui vient du client comme un indice, pas comme une vérité. Les flags UI comme isPro, les valeurs en local storage et les boutons cachés sont faciles à falsifier. Le serveur doit décider d’après vos entitlements stockés.

Un pattern pratique : calculer « ce qui est autorisé » depuis une seule fonction, en utilisant un enregistrement d’entitlement unique. Free peut voir les tableaux de bord mais pas exporter. Pro peut exporter. L’important, c’est que chaque endpoint utilise la même décision.

Petite checklist pour la garde :

• Chargez l’utilisateur et son enregistrement d’entitlement courant depuis la base.
• Calculez allowedFeatures dans une seule fonction (pas de vérifs ad hoc éparpillées).
• Bloquez par défaut quand les données manquent ou sont incertaines.
• Retournez une erreur claire : ce qui a été bloqué et pourquoi.
• Loggez la décision avec l’ID utilisateur et la version de l’entitlement.

Des erreurs claires aident le support (« L’export requiert Pro. Votre plan est Free. »). Elles rendent aussi les logs recherchables quand quelqu’un dit « J’ai payé mais ça dit encore bloqué. »

3) Ajoutez quelques tests qui attrapent les fuites tôt

Restez simple. Vous voulez trois tests : un utilisateur Free est bloqué, un utilisateur payé est autorisé, et un utilisateur avec des entitlements manquants est bloqué. Ceux-ci seuls attrapent beaucoup de fuites de revenus avant la production.

Si vous avez hérité d’un prototype généré par IA, des équipes comme FixMyMess commencent souvent par centraliser ces gardes parce que ça stoppe les fuites sans obliger à une refonte complète.

Webhooks : gérer événements manquants, dupliqués et tardifs

Les webhooks ne sont pas garantis. Ils peuvent arriver en retard, deux fois, dans le désordre, ou jamais. Si votre app suppose « on a reçu le webhook, donc l’accès est correct », vous continuerez de voir des bogues de contrôle de facturation.

Traitez les webhooks comme des notifications d’un changement, pas comme le changement lui-même. Votre app doit pouvoir répondre, maintenant, « que peut faire ce client ? » même si le dernier événement est retardé.

Rendre le traitement des webhooks sûr et digne de confiance

Commencez par vérifier que l’événement est réel. Vérifiez la signature du fournisseur, rejetez les payloads non fiables, et n’activez pas des fonctionnalités uniquement parce qu’un champ de webhook le dit. Recoupez avec l’état courant du client.

Rendez ensuite les handlers idempotents. Si le même événement est traité deux fois, le résultat doit être identique.

Une courte checklist qui évite la plupart des fuites de revenus :

• Vérifiez les signatures et rejetez les requêtes qui échouent à la validation.
• Stockez un event ID et ignorez les doublons déjà traités.
• Appliquez les changements seulement si l’événement est plus récent que ce que vous avez enregistré.
• Revérifiez l’abonnement/les entitlements actuels avant d’accorder l’accès.
• Loggez les échecs avec suffisamment de détails pour rejouer en toute sécurité plus tard.

Gérer les événements hors ordre et manquants

Les événements hors ordre sont courants lors d’upgrades, de remboursements et d’annulations. Utilisez des timestamps (ou des numéros de séquence, si fournis) et comparez-les à votre état stocké. Si un ancien « trial started » arrive après un « paid canceled », ne réécrasez pas l’état plus récent.

Pour les événements manquants, construisez une voie de retry sûre. Queuez le webhook, retentez le traitement, et alertez quand les retries échouent en boucle. Dans les prototypes qui sautent ces garde-fous, un événement perdu peut laisser des fonctionnalités payantes débloquées pendant des jours.

Une bonne règle : les webhooks mettent à jour vos enregistrements, mais votre produit délivre l’accès en se basant sur vos propres entitlements actuels, pas sur le dernier webhook reçu par hasard.

Conditions de concurrence autour des upgrades et downgrades

Les conditions de concurrence sont une voie facile pour que des bogues de facturation se glissent. Elles apparaissent quand deux parties de votre app mettent à jour ou lisent le plan d’un client en même temps, et que l’une voit des données obsolètes. Le résultat est habituellement un accès gratuit (ou des verrous aléatoires) juste quand quelqu’un change de plan.

Un schéma courant : l’utilisateur clique sur Upgrade, l’UI bascule immédiatement sur “Pro”, mais la vérification côté serveur lit encore l’ancien plan depuis la base (ou le cache). Si votre API fait confiance à l’état UI, l’utilisateur obtient des fonctionnalités payantes avant toute confirmation. Si votre API fait confiance à un état ancien, l’utilisateur paie mais voit encore « verrouillé », puis après un refresh ça marche.

Une correction consiste à forcer chaque changement de plan à passer par une seule voie backend. Ne laissez pas l’UI, le handler webhook et un cron nocturne écrire tous au même champ d’entitlement de manières différentes. Choisissez un propriétaire unique des entitlements, et faites en sorte que tout le reste passe par lui.

Il aide aussi de scinder les états pour que l’app puisse dire honnêtement ce qui se passe :

• Payment started (checkout created)
• Payment confirmed (provider says paid)
• Entitlement granted (your system updated access)
• Entitlement revoked (downgrade effective)

Pour éviter les écritures concurrentes, ajoutez un verrou à courte durée ou une vérification de version sur l’enregistrement client lors des changements de plan. Par exemple, stockez un entitlements_version number. Quand vous appliquez un upgrade, écrivez seulement si la version est celle que vous avez lue, puis incrémentez-la. Si elle a changé, réessayez avec des données fraîches.

Exemple concret : un utilisateur upgrade, et au même moment votre cron « fixe » les subscriptions en resynchronisant le plan d’hier. Sans verrou ni vérification de version, l’écriture du cron peut arriver en dernier et annuler l’upgrade. L’UI peut afficher Pro alors que l’API le restreint à Free, ou l’inverse.

Si vous héritez d’un prototype généré par IA, c’est une découverte d’audit courante : multiples écritures de plan, pas de source unique de vérité, et des vérifications d’accès qui dépendent de celui qui a gagné la course.

Faites des entitlements un modèle de données propre et cohérent

La plupart des bogues de contrôle de facturation commencent par une vérité dispersée. Une partie de l’app vérifie une chaîne de plan sur l’enregistrement utilisateur. Une autre vérifie un flag du fournisseur de facturation. Une troisième vérifie l’existence d’un subscription. Quand ils ne sont pas d’accord, soit les gens obtiennent des fonctionnalités payantes gratuitement, soit les clients payants sont bloqués.

Corrigez cela en créant un enregistrement d’entitlement unique que votre app traite comme source de vérité. Stockez-le dans une table (ou un document) et mettez-le à jour depuis les webhooks et les résultats de checkout vérifiés. Incluez des timestamps pour pouvoir raisonner sur ce qui a changé et quand.

Un enregistrement d’entitlement pratique inclut généralement :

• Plan courant (Free, Pro, Team)
• Statut d’abonnement (active, trialing, past_due, canceled)
• Period start et period end (date de renouvellement)
• Entitlement version et updated_at (pour le débogage et le replay)
• Politique de grâce et grace_until (si vous autorisez une période de grâce)

Définissez les périodes de grâce en langage clair et encodez-les dans le modèle. Par exemple : permettre l’accès en lecture seule pendant 3 jours après un paiement échoué, mais bloquer exports et appels API payants immédiatement. L’idée est de faire de « ce qui est autorisé » une règle liée au statut et au temps, pas un tas de conditionnels ad hoc.

Décidez aussi de ce qui se passe en cas de paiement échoué. Le verrou immédiat est le plus simple. Un accès limité peut réduire le churn, mais seulement si c’est appliqué de façon cohérente dans tout le produit.

Enfin, traitez les overrides admin comme des données à part entière. Ils deviennent souvent la cause cachée des bogues de facturation parce que personne ne sait pourquoi un utilisateur est débloqué. Enregistrez qui a changé l’override, quand et pourquoi. Ajoutez une date d’expiration pour les unlocks temporaires. Rendez l’état d’override visible dans l’UI admin. Loggez les décisions d’entitlement (au moins en mode debug) pour pouvoir expliquer allow/deny sans supposer.

Si vous héritez d’un prototype IA, il est courant de trouver 3–5 sources d’entitlement concurrentes. Les consolider est généralement le moyen le plus rapide d’arrêter les fuites sans réécrire toute l’app.

Cas limites qui fuient souvent des revenus

Les bogues de contrôle de facturation se cachent rarement dans le happy path. Ils apparaissent quand de vrais utilisateurs changent d’avis, partagent des comptes, ou rencontrent des problèmes de timing que votre prototype n’a jamais vus.

Les règles trial vs paid peuvent se télescoper de façon surprenante. Une erreur courante est de vérifier isTrialActive en premier et de retourner tôt, même après qu’un utilisateur ait upgrade. Ça peut appliquer des limites d’essai à des utilisateurs payants, ou pire, appliquer des règles d’essai plus permissives que les règles payantes. Faites de « paid beats trial » une règle explicite.

Les downgrades sont une autre fuite silencieuse. Si vous ne verrouillez qu’à la connexion, les utilisateurs peuvent garder un onglet ouvert et continuer d’utiliser des fonctionnalités payantes après un downgrade. La même chose arrive quand vous mettez en cache les entitlements trop longtemps. Si un plan change, votre app a besoin d’un moyen rapide de revérifier l’accès (ou d’invalider le cache) avant les actions sensibles.

Les remboursements et chargebacks nécessitent une politique claire pour l’accès et les données. Si vous ne faites rien, vous pouvez accorder un accès indéfini après la révocation du paiement.

Quelques cas embêtants à tester :

• Deux abonnements actifs (utilisateur abonné deux fois, ou changé de plan sans annuler)
• Mismatch facturation workspace vs utilisateur (un membre hérite accidentellement du plan du propriétaire)
• Contournement par rôle (les admins ont plein accès même sur un plan Free)
• Anciens flags « grandfathered » qui priment sur les contrôles actuels
• Facture manuelle marquée comme payée sans mise à jour des entitlements

Un scénario courant : le propriétaire d’équipe upgrade, puis downgrade immédiatement, et un webhook arrive en retard. Si votre app déverrouille à l’upgrade mais ne se reverrouille jamais au downgrade, les fonctionnalités restent ouvertes.

Erreurs communes et pièges à éviter

Les bogues de contrôle de facturation arrivent généralement parce que les règles vivent à trop d’endroits, et qu’ils ne s’accordent pas tous. Un prototype peut sembler correct dans l’UI, alors que le backend autorise encore des endpoints payants.

La manière la plus rapide de fuir des revenus est de traiter le contrôle d’accès comme un problème front-end. Les boutons et les écrans sont faciles à bypasser avec des appels API directs, des requêtes sauvegardées ou un simple script.

Erreurs courantes à surveiller :

• Gate côté UI uniquement : cacher une fonctionnalité dans l’app, mais ne jamais vérifier le plan côté serveur.
• Vérifications de plan éparpillées : différents fichiers utilisent des règles différentes (nom de plan ici, price ID là, logique d’essai ailleurs).
• Confiance aveugle dans les champs de payload de webhook : accepter le statut du plan depuis un événement sans vérifier qu’il correspond à vos propres enregistrements.
• Pas de sécurité webhook : ignorer retries, doublons ou événements hors ordre et réactiver accidentellement l’accès.
• Environnements mélangés : clés dev en production (ou l’inverse), donc vous « réparez » les mauvaises données et le bogue revient.

Un classique : un utilisateur upgrade, l’UI affiche Pro, mais le backend lit un ancien plan mis en cache pendant 10 minutes. Cette fenêtre suffit à cumuler des exports ou autres actions payantes.

Si vous héritez de code IA, ces problèmes sont souvent intégrés comme des vérifications copiées-collées. Consolider la logique en une seule vérification d’entitlement côté serveur et durcir le traitement des webhooks réduit la probabilité que le bogue revienne après le prochain refactor.

Avant d’envoyer, faites deux tests de sanity :

1. Appelez l’endpoint API payant directement depuis un compte Free.

2. Rejouez le même webhook d’upgrade deux fois, puis envoyez un événement de downgrade tardif, et confirmez que l’accès finit dans le bon état.

Vérifications rapides avant le déploiement ou la relance

Avant de relancer un prototype, faites quelques vérifications rapides qui attrapent la plupart des fuites de facturation. Vous répondez à deux questions : quelqu’un peut-il obtenir une valeur payante sans payer, et est-ce que des clients légitimes peuvent être bloqués ?

Un contrôle rapide réalisable en moins d’une heure avec un utilisateur test et vos logs :

• Essayez des actions payantes depuis un compte Free en appelant directement l’API (pas l’UI). Si un endpoint payant renvoie succès, vous avez une fuite.
• Upgradez un compte test et rafraîchissez depuis un nouvel appareil ou une fenêtre incognito. L’accès doit se débloquer rapidement, et rester débloqué 10 minutes plus tard.
• Downgradez ou faites échouer un paiement, puis retentez les mêmes actions payantes. Elles doivent s’arrêter de façon fiable, même si l’UI affiche encore d’anciennes touches.
• Rejouez les webhooks de facturation. Les handlers doivent être sûrs à exécuter plusieurs fois et le résultat doit être clair dans les logs.
• Ouvrez un écran interne qui montre les entitlements actuels de l’utilisateur, leur source (plan, add-on, trial) et la dernière mise à jour.

Un test réel utile : upgradez un utilisateur puis lancez immédiatement un job payant lourd (export, run IA, action en masse). Si le job démarre avant que les entitlements soient mis à jour, vous avez trouvé une course. Les corrections incluent généralement la vérification des entitlements côté serveur au moment de l’action et faire attendre le flux d’upgrade jusqu’à confirmation du nouvel état.

Vérifiez aussi vos logs. Quand quelque chose tourne mal, vous devez pouvoir répondre « pourquoi cette requête a été autorisée/refusée ? » sans deviner :

• Requête autorisée/refusée parce que l’entitlement X était vrai/faux.
• Event ID du webhook, statut (processed/skipped) et raison.
• Ancien vs nouvel état d’entitlement, avec timestamps.

Exemple : l’upgrade qui débloque des fonctionnalités gratuitement

Une fuite courante paraît inoffensive : un utilisateur clique sur Upgrade, voit « Pro » dans l’UI, et commence immédiatement à utiliser des fonctionnalités payantes. Plus tard, vous constatez qu’il n’a jamais réellement payé, ou que son paiement a échoué, et pourtant il a gardé l’accès.

Imaginez un moment chargé (lancement, email promo ou démo). Un utilisateur upgrade alors que votre app est sous charge, le fournisseur de facturation est lent, et votre app considère « checkout démarré » comme « maintenant Pro ».

Où le bogue se cache

L’UI bascule en Pro sur la base d’un flag local (ou d’un enregistrement mis en cache). Mais le backend voit encore l’utilisateur en Free parce que l’entitlement réel n’est mis à jour que quand un webhook arrive.

Si votre vérification de fonctionnalité dépend de l’état client, d’une session mise en cache ou d’une lecture de base de données en retard, l’utilisateur peut passer la porte. Si l’API fait confiance à un état ancien, l’utilisateur paie mais voit encore « verrouillé », puis après refresh ça marche.

Comment le reproduire (fiablement)

Vous pouvez généralement le déclencher sans outils sophistiqués :

• Ouvrez deux onglets en étant connecté.
• Dans l’Onglet A, cliquez Upgrade et terminez le checkout.
• Dans l’Onglet B, rafraîchissez et appuyez vite sur une fonctionnalité payante (ou spammez le bouton d’action).
• Ajoutez un délai au traitement des webhooks (ou testez dans un environnement lent) et observez ce qui se passe.

Si l’action payante réussit avant que le webhook n’actualise les entitlements, vous avez un trou.

Une correction pratique qui ferme le trou

Traitez les upgrades comme une machine à états côté serveur, pas comme un toggle UI :

• Garde côté serveur : chaque action payante vérifie les entitlements serveur, pas l’étiquette plan côté client.
• État pending : quand le checkout commence, définissez un statut pending_upgrade et gardez les fonctionnalités payantes verrouillées (ou autorisez seulement un aperçu limité).
• Traitement idempotent des webhooks : traitez le même événement deux fois sans effet secondaire, et ignorez les événements hors ordre en utilisant un event ID et des timestamps.

Pour confirmer la correction, répétez le test des deux onglets et vérifiez dans les logs que les actions payantes sont refusées jusqu’à ce que l’entitlement soit réellement actif, puis autorisées seulement après que le webhook (ou le paiement vérifié) ait mis à jour l’état serveur.

Si vous avez hérité d’un prototype IA (Lovable, Bolt, v0, Cursor, Replit), ce bogue exact apparaît souvent parce que le plan est suivi à plusieurs endroits. FixMyMess règle typiquement ça en retraçant chaque vérification de plan, en migrant vers une source de vérité serveur unique, et en durcissant la logique des webhooks pour que « Pro » signifie vraiment payé.

Prochaines étapes : colmater les fuites de revenus sans tout reconstruire

Commencez par écrire les actions exactes qui doivent être payantes. Utilisez des mots simples : « exporter rapport », « inviter coéquipier », « retirer watermark », « utiliser modèle premium ». Cette liste devient votre checklist.

Choisissez un endroit serveur pour jouer le rôle de gardien, et faites en sorte que tout y passe. Si votre app vérifie les plans dans cinq fichiers différents (ou seulement dans l’UI), vous en manquerez un.

Un ordre pratique qui marche pour la plupart des équipes :

• Listez les actions payantes et ajoutez une garde côté serveur utilisée par chaque endpoint payant.
• Renforcez le traitement des webhooks : vérifiez les signatures, stockez les événements et rendez le traitement idempotent.
• Ajoutez des retries pour les webhooks échoués, et gérez les événements tardifs sans casser l’accès.
• Testez les upgrades en contrainte : simulez réseaux lents, doubles clics et deux appareils qui upgrade simultanément.
• Revérifiez downgrades et remboursements pour que l’accès bascule correctement et au bon moment.

Avant de changer la logique, décidez quelle « vérité » vous adopterez pendant la fenêtre d’upgrade. Vous pouvez accorder l’accès seulement après avoir enregistré un paiement confirmé, ou accorder un accès temporaire court et le révoquer automatiquement si le paiement n’aboutit pas. Les deux approches fonctionnent, mais il faut de la cohérence.

Si vous travaillez avec un prototype généré par IA, les problèmes de facturation sont souvent accompagnés d’autres soucis : auth en désordre, secrets exposés, architecture confuse. Si vous voulez une seconde paire d’yeux, FixMyMess (fixmymess.ai) se concentre sur le diagnostic et la réparation des codebases générées par IA, y compris la logique d’entitlement, le traitement des webhooks, le renforcement de la sécurité et la préparation au déploiement.

FixMyMess propose aussi un audit de code gratuit pour localiser où l’accès fuit, puis répare les vérifications de plan et les cas limites de webhook avec une vérification humaine, souvent en 48–72 heures.