Paiement Stripe

Module de paiement Stripe avec checkout session, paiements ponctuels, abonnements récurrents (plans tarifaires), portail client Stripe, gestion des remboursements et webhooks sécurisés.

📋 Schéma Prisma

// === Module Paiement Stripe ===

enum SubscriptionStatus {
  ACTIVE
  TRIALING
  PAST_DUE
  CANCELLED
  UNPAID
}

model StripeCustomer {
  id               String        @id @default(cuid())
  userId           String        @unique
  stripeCustomerId String        @unique
  createdAt        DateTime      @default(now())
  subscription     Subscription?
  payments         Payment[]

  @@map("stripe_customers")
}

model Subscription {
  id                   String             @id @default(cuid())
  stripeCustomerId     String             @unique
  customer             StripeCustomer     @relation(fields: [stripeCustomerId], references: [id])
  stripeSubscriptionId String             @unique
  planId               String
  status               SubscriptionStatus
  currentPeriodStart   DateTime
  currentPeriodEnd     DateTime
  cancelAtPeriodEnd    Boolean            @default(false)
  createdAt            DateTime           @default(now())
  updatedAt            DateTime           @updatedAt

  @@map("subscriptions")
}

model Payment {
  id               String         @id @default(cuid())
  stripeCustomerId String
  customer         StripeCustomer @relation(fields: [stripeCustomerId], references: [id])
  stripePaymentId  String         @unique
  amount           Int
  currency         String         @default("eur")
  status           String
  description      String?
  paidAt           DateTime?
  createdAt        DateTime       @default(now())

  @@map("payments")
}

🔌 Endpoints API

## API Paiement Stripe

POST /api/stripe/checkout          # Créer une Checkout Session
POST /api/stripe/portal            # Créer un lien Portail Client
GET  /api/stripe/subscription      # Statut abonnement courant
GET  /api/stripe/payments          # Historique paiements
POST /api/stripe/webhooks          # Webhook Stripe (public, vérifié par signature)

🛠️ Guide d'implémentation

## Implémentation Paiement Stripe

### Dépendances
```bash
npm install stripe @stripe/stripe-js
```

### Étape 1 — Configuration
```
STRIPE_SECRET_KEY=sk_live_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
STRIPE_PRICE_ID_MONTHLY=price_xxx
```

### Étape 2 — Checkout Session
Créer une Checkout Session Stripe avec:
- Création automatique du StripeCustomer si inexistant
- Mode payment (ponctuel) ou subscription
- URL de succès et d'annulation

### Étape 3 — Webhooks
Route POST /api/stripe/webhooks :
- Vérification signature : `stripe.webhooks.constructEvent()`
- Gérer : checkout.session.completed, customer.subscription.*, invoice.payment_*
- Toujours retourner 200 même en cas d'erreur métier

### Étape 4 — Portail client
Générer un lien Billing Portal pour que le client gère lui-même son abonnement.