Stripe Billing

​

Ce que vous obtenez

• Trois modèles d’accès : sans abonnement, inclus + payant, ou payant uniquement
• Stripe Checkout hébergé — les utilisateurs passent à la version payante sans que vos données de carte ne transitent par votre code
• Portail client — les utilisateurs mettent à jour leurs méthodes de paiement, téléchargent des factures, annulent — tout sur l’interface de Stripe
• Cycle de vie piloté par webhooks — les abonnements se provisionnent et se renouvellent automatiquement ; les utilisateurs payants annulés reviennent au niveau inclus (ou deviennent non autorisés en mode payant uniquement) à la fin de la période
• Application des quotas — utilisation des tokens suivie par période ; interruption en cours de flux avec une invite de mise à niveau structurée
• Pages d’administration pour la gestion des plans et la surveillance des abonnements

​

Prérequis

1. Compte Stripe avec le mode Live activé. Les entreprises constituées à Singapour doivent compléter la vérification KYC (UEN commercial, ID du directeur, compte bancaire). L’approbation prend généralement 1 à 3 jours.
2. Clé API Stripe Live de type Restricted (recommandée plutôt que Standard sk_live_*** — plus facile à révoquer, permissions limitées).
3. Point de terminaison webhook accessible publiquement à <your-domain>/api/webhooks/stripe.
4. Compte bancaire pour les versements. Le règlement multi-devises (par ex. versement en USD vers un compte USD) est recommandé pour les comptes Stripe non-USD par défaut afin d’éviter une fuite de change de 1,5 à 2 % par transaction.

​

Configuration

​

1. Tableau de bord Stripe

​

Créer le produit Pro

1. Catalog → Products → + Add product
2. Name: Pro, description: 5M tokens / month, priority support
3. Pricing: Recurring, monthly, $20.00 USD (adjust to your pricing strategy)
4. Save → copy the resulting price_*** ID (you will UPDATE the local billing_plans table with this value after activation)

​

Créer une clé API restreinte

1. Developers → API keys → + Create restricted key
2. Name: fim-one production
3. Permissions (minimum):
   • Customers: Write
   • Subscriptions: Write
   • Checkout Sessions: Write
   • Customer portal: Write
   • Prices: Read
   • Products: Read
4. Save → copy rk_live_***

​

Enregistrer le point de terminaison du webhook

1. Developers → Webhooks → + Add endpoint
2. URL: https://<your-domain>/api/webhooks/stripe
3. Événements à recevoir:
   • checkout.session.completed
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted
   • invoice.payment_succeeded
   • invoice.payment_failed
4. Après l’enregistrement, cliquez sur “Reveal signing secret” → copiez whsec_***

​

Configurer le règlement multi-devises (recommandé)

1. Paramètres → Comptes bancaires et devises → Ajouter une devise de règlement
2. Sélectionnez la devise de prix (par ex. USD)
3. Attachez le compte bancaire correspondant (par ex. un compte virtuel Aspire USD)
4. Enregistrez — Stripe achemine les frais USD directement vers les versements USD, sans conversion de change

​

2. Backend .env

STRIPE_SECRET_KEY=rk_live_***
STRIPE_WEBHOOK_SECRET=whsec_***
STRIPE_BILLING_RETURN_URL=https://<your-domain>/settings?tab=billing

./deploy.sh   # or: docker compose restart fim-one

​

3. Activer dans Admin

1. Connectez-vous en tant qu’administrateur
2. Admin → System Settings → Access and billing
3. Choisissez une posture (l’instance est toujours dans exactement une) :
   • No subscriptions (logiciel par défaut) — Stripe inutilisé. L’accès par token est le quota mensuel par défaut (0 = illimité).
   • Included + paid — Stripe requis. Les nouveaux utilisateurs arrivent sur le tier inclus ; ils peuvent passer à une version payante. Les utilisateurs payants annulés reviennent au tier inclus à la fin de la période.
   • Paid only — Stripe requis. Pas de tier inclus. Les utilisateurs doivent s’abonner avant de pouvoir appeler les modèles. Les utilisateurs du tier inclus existants conservent leur quota si vous passez de Included + paid.
4. Le backend valide que STRIPE_SECRET_KEY et STRIPE_WEBHOOK_SECRET sont présents lorsque vous choisissez une posture Stripe — si l’un des deux est manquant, il retourne 400
5. À la première activation d’une posture Stripe, le backend exécute une configuration idempotente :
   • Included + paid : initialise le plan inclus (slug=free) + un modèle Pro avec un ID de prix vide ; définit default_plan_id ; remplit rétroactivement les utilisateurs sans plan
   • Paid only : initialise uniquement le modèle Pro ; ne remplit pas rétroactivement
   • Copie default_token_quota sur le plan inclus lors de son initialisation (0 reste 0, illimité)
6. Revenir à No subscriptions est un simple changement de drapeau sans effets secondaires sur les données. Le plan par défaut inclus ne peut pas être supprimé tant que Included + paid est actif.

​

4. Mettez à jour le plan Pro avec votre prix en direct

• Admin → Billing → Plans → Pro → Edit
• Collez votre price_1*** (de l’étape 1) dans Stripe Price ID
• Enregistrez

UPDATE billing_plans
SET stripe_price_id = 'price_1***'
WHERE slug = 'pro';

​

5. Test de fumée

1. Ouvrez /settings?tab=billing en tant qu’utilisateur ordinaire
2. Cliquez sur Switch to Pro
3. Stripe Checkout s’ouvre ; complétez avec une vraie carte à faible montant (remboursement après)
4. Le webhook doit se déclencher — vérifiez dans Stripe Dashboard → Webhooks → les événements récents affichent des réponses 2xx
5. Une ligne d’abonnement apparaît dans la table subscriptions ; users.plan_id bascule à pro
6. L’interface affiche maintenant le plan Pro + le bouton « Manage subscription »

​

Désactiver la facturation

• Tous les points de terminaison /api/billing/* retournent 503
• Le point de terminaison webhook retourne 503 (Stripe réessaiera, puis s’affichera dans Dashboard comme défaillant — c’est normal, vous pouvez désactiver le webhook dans Stripe Dashboard à la place si la facturation est définitivement désactivée)
• L’onglet Plan & Billing destiné aux utilisateurs disparaît
• Le groupe de navigation Admin → Billing est masqué
• La chaîne de quota ignore le niveau de plan et revient directement à default_token_quota

​

Référence de calcul — mathématiques des quotas et des jetons

​

Glossaire

​

Ce qui compte comme un token

• Comptabilisé : tokens de prompt + tokens de completion sur chaque appel de modèle
• Comptabilisé : chaque aller-retour dans un flux d’agent multi-étapes / tool-use (chaque appel de modèle est son propre débit)
• Comptabilisé : demandes d’embedding (ingestion KB, scoring de récupération)
• Non comptabilisé : entrée préparée mais jamais envoyée à un modèle (par exemple, fichiers téléchargés que l’utilisateur abandonne)
• Non comptabilisé : demandes qui échouent avant d’atteindre le fournisseur (erreur d’authentification, pré-vérification de limite de débit)
• Entrée en cache : comptabilisée au prix complet en v1 (aucune remise de cache du fournisseur n’est affichée). v2 peut créditer les tokens de prompt en cache séparément.

​

Sémantique de remplacement à trois états

​

Chaîne de résolution des quotas — v1 (actuelle)

1. users.token_quota        ── NULL? skip. 0? unlimited. N>0? cap at N.
2. users.plan.monthly_token_quota   ── only when access_model is freemium or paid_only
3. paid_only + no plan      ── unentitled (stop; do not fall through)
4. system_settings.default_token_quota  ── used when access_model is off
5. unlimited                ── last resort if everything above is unset

​

Réinitialisation de la période

• Pour les utilisateurs payants, quota_reset_at reflète Subscription.current_period_end. Le gestionnaire webhook invoice.payment_succeeded définit tokens_used_this_period = 0 et avance quota_reset_at à la fin de la nouvelle période à chaque renouvellement réussi.
• Pour les utilisateurs Free (sans abonnement Stripe), un cron horaire réinitialise tokens_used_this_period à 0 à la limite d’un mois calendaire ancrée à la date d’attribution du plan.
• Les changements de plan en cours de période ne réinitialisent pas le compteur — seuls les renouvellements le font. Cela prévient les exploits de recyclage de quota (« s’abonner → utiliser le quota Pro → annuler → s’abonner à nouveau »).

​

Application de la limite en cours de flux

• Vérification préalable à l’entrée de l’appel de chat : chemin le moins coûteux, bloque les demandes que l’utilisateur ne peut pas se permettre de démarrer.
• Pendant le streaming, le nombre de tokens en cours est réévalué à chaque chunk. Le dépassement du plafond ferme le flux avec un cadre terminateur structuré, et non une erreur réseau.
• Le frontend interprète le terminateur et affiche <QuotaExceededDialog> avec un lien profond vers /settings?tab=billing.
• Les réponses non-streaming retournent HTTP 402 avec le corps { code: "QUOTA_EXCEEDED", reset_at, upgrade_url }.

​

Fallback avec facturation désactivée

• L’étape 2 de la chaîne est ignorée — la chaîne se réduit à override → default → unlimited.
• /api/billing/* et /api/webhooks/stripe retournent 503.
• L’onglet utilisateur Plan & Billing et le groupe de navigation Admin → Billing sont masqués.
• Toutes les données de facturation (abonnements, plans, users.plan_id) sont conservées — la réactivation reprend à partir du même état sans migration.

​

Réservé : chaîne de quota v2 — Sièges d’équipe

• Subscription.quantity porte le nombre de sièges (natif Stripe).
• Le plan effectif d’un utilisateur se résout via l’appartenance à l’équipe avant de revenir à son plan personnel :
  effective_plan = team.plan if team_member(user) else user.plan
  
• Le quota est par siège (chaque membre de l’équipe obtient un monthly_token_quota complet), et non un pool partagé. Les pools partagés créent un épuisement au premier arrivé, premier servi et sont contraires aux intérêts des clients.
• La sémantique des remplacements reste inchangée — les administrateurs d’équipe peuvent toujours plafonner fortement les membres individuels via users.token_quota = N, qui se situe au-dessus du plan d’équipe dans la chaîne.

​

Réservé : chaîne de quota v3 — allocation native Org (sans Stripe)

• Nouvelle table org_quota_allocations(user_id, monthly_token_quota, org_id) distribue un budget parent entre les membres.
• Les allocations sont par utilisateur, pas un pool partagé — chaque membre a un SLA individuel clair.
• Chaîne mise à jour :
  override → max(plan_quota, org_allocation) → default → unlimited
  
• max(), pas sum(). Un utilisateur Pro payant n’obtient jamais moins que ce qu’il a payé, même si son administrateur Org définit une allocation basse. Le quota payé via Stripe est sacrosaint.

​

Réservé : solde de crédits à l’usage (dimension v3 séparée)

• Nouvelle table user_credits(user_id, balance_cents, currency) — financée via Stripe Checkout mode='payment'.
• Ordre de consommation : quota d’abonnement en premier, puis solde de crédits (la décrémentation des crédits ne commence qu’après l’épuisement de l’abonnement).
• Le solde de crédits n’est pas remboursable (standard industriel pour les prépayés).
• L’interface expose les deux barres : Quota d'abonnement : 4,2M / 5M utilisés + Crédits : 7,40 $ restants.

​

Valeurs par défaut

​

Modèle de tarification

• Plan d’équipe (sièges Stripe / subscription.quantity)
• Facturation annuelle
• Présentation multi-devises
• Coupons / codes promotionnels
• Gestion des taxes (intégration Stripe Tax — nécessite un examen de conformité distinct)
• Mesure basée sur l’utilisation / frais de dépassement
• Solde de crédit à l’usage (recharge unique)

​

Dépannage