Apex Coach — Skill Stripe

Starter — DEPRECATED (prod_U16BSelEMURdU9)

Ne jamais utiliser ce Price ID pour un nouvel utilisateur. Legacy uniquement.

Remises affichées : -45% sur Coaching annuel, -33% sur Coaching Pro annuel.

Essai gratuit : 7 jours Coaching Pro complet, sans CB. Géré par lib/subscription/trial-subscription.ts.

Architecture Stripe dans le projet

lib/stripe/
├── client.ts                ← getStripe() singleton
├── webhook-handlers.ts      ← Handlers par événement Stripe
├── errors.ts                ← Retry logic + backoff pour appels Stripe
├── payment-utils.ts         ← createPaymentRecord()
├── subscription-schedule.ts ← Gestion des schedule (upgrade/downgrade)
└── logger.ts                ← webhookLogger, subscriptionLogger

app/api/
├── checkout/                ← Création sessions Stripe Checkout
├── webhooks/stripe/         ← Point d'entrée webhooks (vérification signature)
└── create-portal-session/   ← Portail client Stripe (annulation, changement CB)

lib/config/pricing.ts        ← Source de vérité : plans, prix, Stripe Price IDs

Événements Stripe gérés (webhook-handlers.ts)

Pattern webhook — obligatoire

// app/api/webhooks/stripe/route.ts
export async function POST(request: Request) {
  const body = await request.text()
  const signature = request.headers.get('stripe-signature')!

  let event: Stripe.Event
  try {
    // ✅ Toujours vérifier la signature — jamais skipper
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    )
  } catch (err) {
    return apiError('Signature invalide', 400)
  }

  // ✅ Idempotence — vérifier si déjà traité avant d'agir
  // ✅ Utiliser le client admin Supabase (bypass RLS nécessaire)
  // ✅ Retry avec backoff sur les opérations DB (RETRY_CONFIG dans webhook-handlers.ts)
  // ✅ Retourner 200 rapidement — Stripe re-tentera si timeout
}

Checkout — création de session

// Pattern standard pour créer une session Stripe Checkout
const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  payment_method_types: ['card'],
  line_items: [{
    price: getStripePriceId(planId, billingInterval), // lib/config/pricing.ts
    quantity: 1,
  }],
  success_url: `${baseUrl}/checkout/success?session_id={CHECKOUT_SESSION_ID}`,
  cancel_url: `${baseUrl}/pricing`,
  metadata: {
    // ⚠️ Mettre UNIQUEMENT les données nécessaires au webhook
    // Pas de PII, pas de données de santé
    planId,
    billingInterval,
    questionnaireId, // pour récupérer les données après paiement
  },
})

Réconciliation (cron 3h00 quotidien)

Le cron /api/cron/reconcile-subscriptions synchronise Stripe → Supabase :

1. Récupère toutes les subscriptions active ou trialing en base
2. Vérifie leur statut réel via l'API Stripe
3. Met à jour les discordances (ex: subscription annulée dans Stripe mais active en base)

Si la réconciliation échoue → Sentry P2 + log subscription_updated dans audit_logs.

Upgrade / Downgrade de plan

Utiliser lib/stripe/subscription-schedule.ts pour les changements de plan en cours de période :

• Upgrade immédiat : prorate_behavior: 'create_prorations'
• Downgrade en fin de période : prorate_behavior: 'none' + schedule

Voir docs/PRORATION_POLICY.md pour la politique complète.

Variables d'environnement requises

STRIPE_SECRET_KEY=sk_live_...          # Jamais exposé côté client
STRIPE_WEBHOOK_SECRET=whsec_...        # Différent entre dev et prod
STRIPE_PRICE_COACHING_MONTHLY=price_...
STRIPE_PRICE_COACHING_YEARLY=price_...
STRIPE_PRICE_COACHING_PRO_MONTHLY=price_...
STRIPE_PRICE_COACHING_PRO_YEARLY=price_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_... # Seule clé exposée au client

Checklist avant de déployer un changement Stripe

• Le webhook secret est différent entre dev (whsec_test_...) et prod (whsec_live_...)
• Les Price IDs sont ceux de l'environnement correct (test vs live)
• Le webhook est idempotent (double déclenchement ne crée pas de doublon)
• Un audit log est déclenché pour chaque changement de subscription
• Le client admin Supabase est utilisé (RLS bypass nécessaire pour webhooks)
• Les métadonnées checkout ne contiennent pas de PII ou données santé

Carte de délégation