Configuration de Stripe (exploitation)

Cette page s'adresse à l'équipe qui exploite Maketools. Le service billing utilise le SDK officiel de Stripe : Checkout, portail client et webhooks. Un compte Stripe se configure avec le script scripts/billing/stripe-setup.ts, puis quelques réglages se font à la main dans le Dashboard. Mode test pour le staging, mode live pour la production.

Le script de configuration

# Simulation : liste ce qui serait créé ou mis à jour, n'écrit rien
STRIPE_SECRET_KEY=sk_test_… bun scripts/billing/stripe-setup.ts \
  --base-url https://staging.exemple.fr --dry-run

# Mode test (staging)
STRIPE_SECRET_KEY=sk_test_… bun scripts/billing/stripe-setup.ts --base-url https://staging.exemple.fr

# Mode live (production) : --live est obligatoire avec une clé live, et refusé avec une clé de test
STRIPE_SECRET_KEY=sk_live_… bun scripts/billing/stripe-setup.ts --base-url https://exemple.fr --live

--base-url est l'origine du site (https, ou http://localhost:<port> en mode test). Le script est idempotent : il compare chaque ressource à ce qu'elle doit être et n'écrit que la différence ; relancé sur un compte à jour, il n'écrit rien. Il termine par un résumé (une ligne par ressource : créée, mise à jour, inchangée ou à faire à la main) et la liste des étapes manuelles qu'il a repérées. Mode d'emploi détaillé : scripts/billing/README.md.

Il configure :

1. Deux produits, maketools_plus et maketools_pro (identifiants fixés à la création, métadonnée plan), code fiscal Stripe Tax txcd_10103001 (logiciel en tant que service, usage professionnel), unité « siège ».

2. Quatre prix, en EUR, hors taxes (comportement fiscal exclusif), à l'unité (licensed, pas metered) : la quantité de l'abonnement est le nombre de sièges, ajusté chaque jour par la tâche billing-seat-sync (voir Sièges et membres actifs).

   Clé de recherche	Offre	Montant HT par siège
   maketools_plus_monthly	Plus	6 € par mois
   maketools_plus_yearly	Plus	60 € par an
   maketools_pro_monthly	Pro	10 € par mois
   maketools_pro_yearly	Pro	100 € par an

3. Stripe Tax : siège social (149 avenue du Maine, 75014 Paris) comme adresse d'origine, code fiscal et comportement HT par défaut, et enregistrement à la TVA française. Si Stripe Tax n'est pas encore activé sur le compte, le script continue et l'indique comme étape manuelle.

4. Portail client : historique des factures, moyen de paiement, coordonnées de facturation (adresse, email, nom, téléphone, numéro de TVA), résiliation en fin de période sans remboursement au prorata, avec le questionnaire de résiliation (trop cher, fonctionnalités manquantes, autre service, peu utilisé, service client, trop complexe, qualité, autre), et changement d'offre entre les quatre prix, avec facturation immédiate de la différence. Le changement de quantité n'est pas proposé : les sièges sont gérés par Maketools. Les liens affichés sont les conditions de vente et la politique de confidentialité en français ; le retour mène à <site>/admin.

5. Webhook <site>/api/billing/stripe/webhook (par CloudFront : l'API refuse les appels qui ne passent pas par lui), abonné exactement aux événements que traite le backend et figé sur la même version d'API. Son secret de signature (whsec_…) n'est renvoyé par Stripe qu'à la création : le script l'affiche une seule fois, avec la commande qui l'enregistre dans les secrets de l'environnement.

Les montants ne vivent que dans Stripe et dans le catalogue du script (scripts/billing/stripe-catalog.ts, la source que le script pousse) ; un test vérifie que les prix affichés par le site correspondent à ce catalogue. Le backend ne connaît aucun Price ID : il retrouve l'offre d'un abonnement par la clé de recherche de son prix, la même en test et en live. Un abonnement sur un prix qui n'a ni l'une de ces quatre clés, ni le produit maketools_plus ou maketools_pro, ne donne aucun droit (alerte billing_unknown_price).

Changer un prix

Un prix Stripe ne se modifie pas. Après un changement de montant dans le catalogue, le script crée un nouveau prix qui reprend la clé de recherche, puis désactive l'ancien. Les abonnements en cours restent sur l'ancien prix : il n'a plus de clé, mais le backend reconnaît toujours leur offre par le produit Stripe (maketools_plus ou maketools_pro) ; ils paient l'ancien montant tant qu'ils n'ont pas migré. Le résumé du script les signale ; les passer sur le nouveau prix (Dashboard Stripe, abonnement, « Mettre à jour l'abonnement », sans prorata : le nouveau montant s'applique au renouvellement). Une hausse est notifiée aux clients au moins 30 jours avant le renouvellement auquel elle s'applique (conditions de vente, article 5.4) : lancer le script une fois ce préavis donné, et mettre à jour les prix affichés par le site en même temps.

Étapes manuelles

À faire une fois par compte, dans le Dashboard Stripe :

1. Activer le compte : vérification d'identité (KYC) et compte bancaire de versement.
2. Informations publiques de l'entreprise : raison sociale MAKETOOLS SAS, SIREN 990 247 603 (RCS Paris), numéro de TVA FR63 990 247 603, adresse du siège, email du support.
3. Image de marque de Checkout, du portail et des factures : logo, icône, couleurs.
4. Factures : préfixe de numérotation, et pied de facture par défaut portant les mentions obligatoires entre professionnels en France : pénalités de retard au taux de la BCE majoré de 10 points, indemnité forfaitaire de 40 € pour frais de recouvrement (articles L. 441-10 et D. 441-5 du Code de commerce), pas d'escompte pour paiement anticipé. Le backend pose aussi ce pied sur chaque client Stripe qu'il crée ; le réglage du compte couvre les autres cas.
5. Stripe Tax, si le script l'a signalé : l'activer, puis relancer le script.
6. Impayés : Smart Retries activé, et « marquer l'abonnement comme impayé » après la dernière tentative.
7. Clé du backend : une clé restreinte plutôt que la clé secrète (droits ci-dessous).

Secrets de l'environnement

En staging et en prod, ils sont conservés dans AWS Secrets Manager (auto-hébergement sur AWS), jamais dans le code ni dans les images. Poser les valeurs : bun run infra:secrets <env> --set StripeSecretKey, puis --set StripeWebhookSecret (valeur lue sur l'entrée standard ; deploy/secrets.md). Il n'y a plus de Price ID à enregistrer.

Droits d'une clé restreinte :

• backend : écriture sur Customers, Checkout Sessions, Customer portal, Subscriptions et Invoices, lecture sur Prices et Refunds ;
• script de configuration (à part, gardée hors des secrets du backend) : écriture sur Products, Prices, Tax settings, Tax registrations, Customer portal (configurations) et Webhook endpoints.

Les sessions Checkout et portail client sont limitées à 10 par heure et par organisation, les resynchronisations depuis Stripe à 20 par heure, et les aperçus de prochaine facture à 60 par heure (mis en cache une minute).

Développement local

Sans StripeSecretKey (le défaut de deploy/env/local.env.example), la facturation est désactivée proprement : toutes les organisations sont en Free, les boutons Checkout expliquent que Stripe n'est pas configuré, et le webhook répond ERR_BILLING_NOT_CONFIGURED.

Pour sortir une organisation du Free en local, activez Enterprise avec le script d'administration (ci-dessous).

Pour essayer le vrai parcours en mode test :

1. configurer un compte de test : --base-url http://localhost:4200 (le script ne crée pas de webhook, Stripe ne pouvant pas joindre localhost) ;
2. lancer stripe listen --forward-to localhost:4000/api/billing/stripe/webhook, qui affiche un secret whsec_… ;
3. placer la clé de test et ce secret dans deploy/env/local.env (jamais commité), puis lancer ./deploy/set-local-secrets.sh.

Activer Enterprise

Enterprise est activée par un administrateur de la plateforme via l'API interne billing.setEnterprisePlan, avec le script scripts/admin/enterprise.ts (confirmation explicite : retaper le slug de l'organisation ; opérateur nommé ; audité en billing.enterprise.granted ou billing.enterprise.revoked). En local, depuis backend/ :

bun ../scripts/encore.ts exec -- \
  bun ../scripts/admin/enterprise.ts grant acme --operator "Jane Ops" --reason "Devis 2026-042"

En staging et en prod, l'activer depuis la fiche de l'organisation dans la console d'exploitation (bun run console), qui appelle la même API interne par une requête signée, sous le nom de la clé d'opérateur. Si l'organisation avait un abonnement Stripe, le résilier depuis le tableau de bord Stripe.

Données conservées par Maketools

Identifiants Stripe du client et de l'abonnement, statut, période, sièges, montant unitaire HT et devise du prix, dates de début, de demande de résiliation et de fin, raison choisie dans le questionnaire de résiliation (jamais le commentaire libre), et identifiants des événements de webhook traités (idempotence). Pour les statistiques internes de Maketools, un registre des paiements : pour chaque facture d'abonnement (payée ou en échec) et chaque remboursement, son identifiant Stripe, l'organisation, le montant HT, la taxe, la devise, l'offre et la date. Aucun numéro de carte, coordonnée bancaire ni adresse de facturation : Stripe est sous-traitant et les conserve. Tout est effacé avec l'organisation.