Setup Stripe (clés API + portail)

Setup initial du compte Stripe pour activer billing, subscriptions, refunds, coupons. Pour les détails d'usage (webhook events, page admin), voir Billing et Webhooks Stripe.

1. Créer le compte + activer test mode

1. Compte sur stripe.com (Standard, pas Express/Custom)
2. Reste en Test mode (toggle en haut à droite du dashboard) pendant tout le dev
3. Renseigne le minimum : nom de l'entreprise, pays, devise par défaut

2. Créer la Secret Key

Dashboard Stripe → Developers → API keys → Create restricted key.

Étape 1 — Cas d'usage

Stripe te propose 3 cas d'usage :

Étape 2 — Modèle d'autorisation

Stripe propose 4 templates :

Étape 3 — Permissions à vérifier / ajouter

Le template "Recurring subscriptions and billing" inclut déjà 90% du nécessaire, mais il manque souvent Refunds + Charges. Après avoir cliqué "Choisir votre offre →", vérifie / ajoute ces 3 lignes à la main :

Tableau complet des permissions utilisées par le boilerplate :

💡 En dev, tu peux créer une clé Standard non-restricted (sk_test_xxx) — plus simple, pas de blocage si tu rajoutes une feature qui utilise une nouvelle resource. En prod, restricted obligatoire (principe du moindre privilège).

3. Variables d'env

Récupère 2 clés du dashboard Developers → API keys :

# .env

# Côté serveur — JAMAIS exposé au browser
STRIPE_SECRET_KEY=sk_test_...

# Côté client — affichée publiquement (rarement utile chez nous, le checkout
# est server-side, mais Stripe.js peut en avoir besoin pour Elements)
STRIPE_PUBLISHABLE_KEY=pk_test_...

# Webhook signing secret — généré à l'étape 4
STRIPE_WEBHOOK_SECRET=whsec_...

4. Webhook (Stripe → ton app)

Voir la doc complète : Webhooks Stripe.

En local (dev)

Installe la Stripe CLI puis :

stripe listen --forward-to localhost:3005/api/billing/webhook

La commande affiche un whsec_ de dev — copie-le dans .env → STRIPE_WEBHOOK_SECRET=whsec_xxx.

Garde la commande tournée pendant que tu testes les flows (checkout, cancel…).

En prod

Dashboard → Developers → Webhooks → Add endpoint :

1. URL : https://ton-domaine.com/api/billing/webhook
2. Events à écouter :
   • checkout.session.completed
   • customer.subscription.updated
   • invoice.payment_succeeded
   • invoice.payment_failed
   • invoice.upcoming
   • customer.subscription.trial_will_end
   • customer.subscription.deleted
3. Copie le Signing secret → STRIPE_WEBHOOK_SECRET dans tes env de prod

5. Activer le Customer Portal

Stripe → Settings → Billing → Customer portal → Activate test link.

Configure :

• ✅ Allow customers to update payment methods
• ✅ Allow customers to cancel subscriptions (Immediately ou At period end)
• ✅ Allow customers to switch plans (optionnel)
• Branding : logo + couleur primaire pour matcher ton app

Sans cette activation, le bouton "Gérer mon abonnement" retourne 400.

6. Créer tes plans (auto-sync Stripe)

/admin/plans dans ton app (mode admin) → Nouveau plan.

Bonne nouvelle : tu n'as pas besoin d'aller dans le Dashboard Stripe. Quand tu sauvegardes un plan avec un prix > 0, le boilerplate appelle l'API Stripe et crée automatiquement :

• Le Product (avec nom + description venant des champs localisés)
• Un Price récurrent mensuel si priceMonthly > 0
• Un Price récurrent annuel si priceYearly > 0

Les stripeProductId / stripePriceIdMonthly / stripePriceIdYearly sont remplis automatiquement et persistés en DB.

Modifier un prix

Stripe n'autorise pas la modification d'un Price existant (immutable). Si tu changes priceMonthly: 2900 → 2900 → 3900 :

1. Le boilerplate archive l'ancien Price (active: false)
2. Crée un nouveau Price (price_xxx2)
3. Met à jour stripePriceIdMonthly en DB

Les subscriptions déjà actives sur l'ancien Price continuent à fonctionner — elles facturent toujours le même montant jusqu'au prochain renouvellement. Seuls les nouveaux checkouts utilisent le nouveau Price.

Supprimer un plan

À la suppression côté DB, le boilerplate appelle Stripe pour archiver le Product et tous ses Prices actifs (pas un delete — Stripe rejette le delete si des subs existent).

Lier à un Product Stripe existant

Si tu as déjà créé tes Products manuellement dans le Dashboard, tu peux toujours coller les IDs dans les 3 champs Stripe du plan editor. Le sync respecte les IDs existants et update juste le Product en place.

Si Stripe n'est pas configuré

Sans STRIPE_SECRET_KEY en .env, le sync est skip silencieusement. Le plan reste en DB avec des stripeProductId / stripePriceId null, et le flow checkout ne fonctionnera pas tant que tu n'auras pas configuré Stripe

• rééditer/sauvegarder le plan pour déclencher le sync.

Détails : Plans.

7. Test du flow complet

Flow standard

1. Crée un compte user dans l'app
2. /account/upgrade → choisis un plan
3. Stripe Checkout s'ouvre
4. Carte test : 4242 4242 4242 4242 / n'importe quelle date future / n'importe quel CVC / ZIP 12345
5. Tu reviens sur l'app → l'abonnement apparaît dans /account/settings → Facturation
6. La CLI Stripe en parallèle affiche les events reçus — tu dois voir tous en [200] :

--> payment_intent.succeeded           [200]
--> customer.subscription.created      [200]
--> invoice.created                    [200]
--> invoice.finalized                  [200]
--> invoice.paid                       [200]
--> invoice.payment_succeeded          [200]
--> checkout.session.completed         [200]

7. /admin/billing (admin) → tu vois la sub avec le MRR

Cartes test Stripe

Pour tous ces tests, utilise n'importe quelle date future (12/30), n'importe quel CVC (123), n'importe quel ZIP (12345). C'est uniquement le numéro de carte qui détermine le comportement.

✅ Paiements qui réussissent

🔐 3D Secure (authentification additionnelle)

❌ Paiements qui échouent

⚠ Scénarios async

📋 Liste complète

stripe.com/docs/testing#cards

Tester des events sans passer par le browser

La Stripe CLI permet de fire des fake events directement :

stripe trigger checkout.session.completed
stripe trigger customer.subscription.deleted
stripe trigger invoice.payment_failed
stripe trigger charge.dispute.created

⚠ Les events fake n'ont pas de vraie metadata.userId — notre handler checkout.session.completed les ignore avec un log. C'est attendu (sécurité). Pour un test complet end-to-end, repasse par le vrai flow /account/upgrade.

Test clocks (avancer le temps)

Pour tester un renouvellement ou la fin d'un trial sans attendre 30 jours :

# Crée un test clock
stripe test_helpers test-clocks create --frozen-time=$(date -u +%s)

# Attache un customer au clock puis avance le temps
stripe test_helpers test-clocks advance <clock_id> --frozen-time=<future_timestamp>

Le clock va déclencher tous les events de subscription qui se seraient normalement passés dans cette période (renewal, trial end, etc.).

Tester un refund admin

1. Fais un paiement réussi (carte 4242 4242 4242 4242)
2. Va dans /admin/billing (admin)
3. Menu actions sur la row → "Rembourser le dernier paiement"
4. Tu dois voir dans stripe listen : --> charge.refunded [200]
5. Côté Stripe Dashboard → Payments → le PaymentIntent passe en Refunded

8. Passer en live

Quand tu es prêt à shipper :

1. Active ton compte Stripe (remplis KYC : numéro SIRET, RIB, ID)
2. Toggle Test mode → Live mode
3. Recrée les mêmes Products + Prices (Stripe ne sync pas test ↔ live)
4. Recrée la restricted key en live avec les permissions ci-dessus
5. Recrée le webhook en live (URL prod cette fois)
6. Update tes env de prod avec les nouvelles clés sk_live_xxx / pk_live_xxx / whsec_xxx
7. Update les Price IDs des plans dans /admin/plans (les IDs test ne marchent pas en live)

Sécurité

• Ne commit jamais STRIPE_SECRET_KEY (déjà dans .gitignore via .env)
• Restricted keys > Standard keys en prod
• Si une clé fuite : Roll immédiatement (Developers → API keys → Roll key)
• Le webhook valide la signature via STRIPE_WEBHOOK_SECRET — sans ça, n'importe qui peut POST /api/billing/webhook avec du JSON Stripe-shaped. Notre handler reject les requests non-signées.

Allez plus loin

• Billing (admin + user) — pages billing et actions admin
• Webhooks Stripe — détail events + idempotence
• Plans tarifaires — config des plans + Price IDs
• Coupons — codes promo synchronisés Stripe