Configuration de Stripe

ScaleRocket utilise Stripe pour la facturation par abonnement. Les utilisateurs choisissent un plan sur la page de tarification, passent en caisse via Stripe, et l'état de leur abonnement se synchronise avec votre base de données via des webhooks.

Important : Vous allez tout configurer en Test mode d'abord. Quand vous serez prêt à accepter de vrais paiements, vous referez la configuration en Live mode — les produits, prix et webhooks sont complètement séparés entre les deux modes. Rien n'est transféré.

Étape 1 : Créer un compte Stripe

1. Allez sur stripe.com et inscrivez-vous
2. Vous démarrez en Test mode par défaut (bouton bascule en haut à gauche)
3. Gardez le Test mode actif pour l'instant — vous passerez en Live mode lors du déploiement en production

Étape 2 : Créer des produits et des prix (Test Mode)

Vous avez deux options : manuellement via le Stripe Dashboard, ou automatiquement via le Stripe MCP.

Option A : Manuel (Stripe Dashboard)

1. Dans le Stripe Dashboard, assurez-vous d'être en Test mode
2. Allez dans Product catalog → Add product
3. Remplissez :
   • Name — ex. "Starter"
   • Description — ex. "For individuals getting started"
4. Ajoutez deux prix :
   • Monthly — ex. 29$/mois (Recurring)
   • Yearly — ex. 290$/an (Recurring)
5. Cliquez sur Save product
6. Copiez chaque Price ID depuis la page de détail du produit (commence par price_)
7. Répétez pour chaque plan (Starter, Pro, Agency)

Option B : Via IA + MCP (Recommandé pour les Vibecoders)

Si vous avez le Stripe MCP configuré dans votre .mcp.json, vous pouvez demander à votre assistant IA de créer les produits pour vous :

Prompt : "Create 3 Stripe products in TEST mode for my SaaS:

1. Starter — $29/month, $290/year
2. Pro — $79/month, $790/year
3. Agency — $199/month, $1990/year Each product needs both a monthly and yearly recurring price. Give me the Price IDs for each."

L'IA créera les produits et retournera les Price IDs. Copiez-les pour l'étape suivante.

Étape 3 : Configurer les tarifs dans votre application

Ouvrez la configuration des tarifs et remplacez les Price IDs provisoires par les vrais Price IDs de test :

// packages/config/src/pricing.ts
export const pricingPlans: PricingPlan[] = [
  {
    id: "starter",
    name: "Starter",
    description: "For individuals getting started",
    price: { monthly: 29, yearly: 290 },
    stripePriceId: {
      monthly: "price_1Abc...",  // ← Your TEST mode Price ID
      yearly: "price_1Def...",   // ← Your TEST mode Price ID
    },
    features: ["50 credits/month", "Email support", "PNG/JPG exports"],
    limits: { credits: 50, storage: "1GB", apiAccess: false },
  },
  // ... Pro and Agency plans
];

Vous devez aussi mettre à jour le mapping PRICE_TO_PLAN dans la fonction webhook pour qu'elle sache quel Stripe Price ID correspond à quel plan :

// supabase/functions/stripe-webhook/index.ts
const PRICE_TO_PLAN: Record<string, string> = {
  "price_1Abc...": "starter",   // monthly
  "price_1Def...": "starter",   // yearly
  "price_1Ghi...": "pro",       // monthly
  "price_1Jkl...": "pro",       // yearly
  "price_1Mno...": "agency",    // monthly
  "price_1Pqr...": "agency",    // yearly
};

// convex/stripe.ts
const PRICE_TO_PLAN: Record<string, string> = {
  "price_1Abc...": "starter",   // monthly
  "price_1Def...": "starter",   // yearly
  "price_1Ghi...": "pro",       // monthly
  "price_1Jkl...": "pro",       // yearly
  "price_1Mno...": "agency",    // monthly
  "price_1Pqr...": "agency",    // yearly
};

Étape 4 : Configurer les webhooks (Test Mode)

Stripe envoie des événements (abonnement créé, paiement réussi, etc.) à votre endpoint webhook. ScaleRocket les traite via votre backend.

Développement local

Utilisez le Stripe CLI pour rediriger les événements vers votre environnement local :

# Install the Stripe CLI
brew install stripe/stripe-cli/stripe  # macOS
# or: scoop install stripe              # Windows
# or: see https://stripe.com/docs/stripe-cli

# Login to your Stripe account
stripe login

# Forward webhooks to your local Supabase Edge Function
stripe listen --forward-to http://localhost:54321/functions/v1/stripe-webhook

# supabase/.env
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Forward webhooks to your local Convex HTTP endpoint
stripe listen --forward-to http://localhost:3210/stripe-webhook

npx convex env set STRIPE_SECRET_KEY sk_test_...
npx convex env set STRIPE_WEBHOOK_SECRET whsec_...

Gardez le CLI en cours d'exécution dans un terminal séparé pendant le développement. Il doit être actif pour que les webhooks atteignent votre serveur local.

Étape 5 : Définir les variables d'environnement (Test Mode)

# apps/app/.env.local — client-side (safe to expose)
VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...

# supabase/.env — server-side (Edge Functions)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# apps/app/.env.local — client-side (safe to expose)
VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...

# Convex environment variables — server-side
npx convex env set STRIPE_SECRET_KEY sk_test_...
npx convex env set STRIPE_WEBHOOK_SECRET whsec_...

Étape 6 : Tester un paiement

1. Démarrez votre serveur de développement : pnpm dev
2. Démarrez Supabase en local : npx supabase start
3. Démarrez le redirecteur de webhooks du Stripe CLI (Étape 4)
4. Allez sur localhost:5173/billing (application dashboard)
5. Cliquez sur un plan et finalisez le paiement avec la carte de test :

Utilisez n'importe quelle date d'expiration future et n'importe quel CVC à 3 chiffres.

Après le paiement, vérifiez :

• La table subscriptions dans Supabase a une nouvelle ligne avec status: "active"
• La table credits a été mise à jour avec l'allocation mensuelle du plan
• Le tableau de bord utilisateur affiche le plan actif et le solde de crédits
• Le Stripe Dashboard affiche l'abonnement sous Customers

Passage en production : passer en Live Mode

Quand vous êtes prêt à accepter de vrais paiements, vous devez refaire toute la configuration Stripe en Live mode. Le Test mode et le Live mode sont complètement séparés — les produits, prix, clients et webhooks ne sont PAS transférés.

Checklist pour le passage en production :

1. Activer votre compte Stripe

Complétez la vérification d'entreprise dans Stripe Dashboard → Settings → Business details. Vous aurez besoin du nom de votre entreprise, de votre adresse et de votre compte bancaire.

2. Recréer les produits et les prix en Live mode

Passez en Live mode dans le Stripe Dashboard (bouton bascule en haut à gauche), puis recréez tous vos produits et prix.

Manuel : Même processus que l'Étape 2 Option A, mais en Live mode.

Via IA + MCP : Si vous avez utilisé le MCP pour créer les produits de test, vous devez aussi les recréer en Live mode :

Prompt : "Switch my Stripe to LIVE mode and recreate these 3 products:

1. Starter — $29/month, $290/year
2. Pro — $79/month, $790/year
3. Agency — $199/month, $1990/year Give me the new LIVE Price IDs."

3. Mettre à jour les Price IDs dans votre code

Remplacez TOUS les Price IDs de test par les nouveaux Price IDs live dans :

packages/config/src/pricing.ts                     → stripePriceId fields
supabase/functions/stripe-webhook/index.ts         → PRICE_TO_PLAN mapping (Supabase)
convex/stripe.ts                                   → PRICE_TO_PLAN mapping (Convex)

4. Créer un webhook Live

1. Allez dans Developers → Webhooks dans le Stripe Dashboard (assurez-vous d'être en Live mode)
2. Cliquez sur Add endpoint
3. Définissez l'URL vers votre endpoint backend :

https://YOUR_PROJECT_REF.supabase.co/functions/v1/stripe-webhook

https://YOUR_DEPLOYMENT.convex.site/stripe-webhook

4. Sélectionnez ces événements :
   • checkout.session.completed
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted
   • invoice.payment_succeeded
   • invoice.payment_failed
5. Cliquez sur Add endpoint
6. Copiez le Signing secret (whsec_...)

Critique : C'est un NOUVEAU webhook avec un NOUVEAU signing secret. Votre webhook de test est séparé et reste actif pour le développement.

5. Mettre à jour les secrets de production

npx supabase secrets set STRIPE_SECRET_KEY=sk_live_...
npx supabase secrets set STRIPE_WEBHOOK_SECRET=whsec_...   # ← the LIVE signing secret

npx convex env set STRIPE_SECRET_KEY sk_live_...
npx convex env set STRIPE_WEBHOOK_SECRET whsec_...   # ← the LIVE signing secret

6. Mettre à jour la publishable key

Dans votre tableau de bord Vercel pour apps/app, mettez à jour :

VITE_STRIPE_PUBLISHABLE_KEY=pk_live_...

7. Tester avec une vraie carte

Effectuez un petit achat réel (1$ ou votre plan le moins cher), vérifiez que l'abonnement est créé, puis remboursez-le dans le Stripe Dashboard.

Résumé : Test vs Live

Prochaines étapes

• Configurer les emails transactionnels pour les reçus de paiement
• Configurer le système de crédits pour la facturation à l'usage
• Déployer en production avec la checklist complète de production