# Abonnements & Paiements (Stripe)

---

## Plans disponibles

| Plan | Description |
|------|-------------|
| FREE | Accès limité (après inscription) |
| BRONZE | Entrée de gamme |
| SILVER | Standard |
| GOLD | Avancé |
| PLATINIUM | Entreprise |

Les plans BRONZE/SILVER/GOLD/PLATINIUM sont disponibles en facturation **mensuelle** ou **annuelle**.

---

## Architecture

Le système utilise Stripe pour la gestion des paiements. Chaque organisation a exactement un enregistrement `subscriptions`.

```
Organization 1──1 Subscription
               └── stripe_customer_id (Stripe Customer)
               └── stripe_subscription_id (Stripe Subscription)
```

---

## API

| Méthode | Route | Description |
|---------|-------|-------------|
| GET | /api/v1/subscriptions/current | Abonnement courant de l'org |
| POST | /api/v1/subscriptions/create-checkout | Créer session Stripe Checkout |
| POST | /api/v1/subscriptions/cancel | Annuler l'abonnement |
| POST | /api/v1/subscriptions/webhook | Webhook Stripe (signature HMAC) |
| GET | /api/v1/subscriptions/plans | Liste des plans disponibles |

---

## Configuration

```bash
# .env backend
STRIPE_SECRET_KEY=sk_test_xxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxx

# Price IDs depuis le Dashboard Stripe
STRIPE_SILVER_MONTHLY_PRICE_ID=price_xxxx
STRIPE_SILVER_YEARLY_PRICE_ID=price_xxxx
STRIPE_GOLD_MONTHLY_PRICE_ID=price_xxxx
STRIPE_GOLD_YEARLY_PRICE_ID=price_xxxx
STRIPE_PLATINIUM_MONTHLY_PRICE_ID=price_xxxx
STRIPE_PLATINIUM_YEARLY_PRICE_ID=price_xxxx
```

---

## Webhook Stripe

Le endpoint `/api/v1/subscriptions/webhook` reçoit les événements Stripe.

**Événements gérés** :
- `checkout.session.completed` — activation abonnement
- `customer.subscription.updated` — changement de plan
- `customer.subscription.deleted` — annulation
- `invoice.payment_succeeded` — paiement réussi
- `invoice.payment_failed` — paiement échoué → statut `past_due`

Le secret `STRIPE_WEBHOOK_SECRET` est utilisé pour vérifier la signature de chaque événement.

### Configurer le webhook en local (test)

```bash
# Installer Stripe CLI
stripe listen --forward-to localhost:4000/api/v1/subscriptions/webhook
```

---

## Statuts d'abonnement

| Statut | Description |
|--------|-------------|
| active | Abonnement en cours, paiement OK |
| trialing | Période d'essai |
| past_due | Paiement en retard |
| cancelled | Annulé |
| pending_payment | En attente de paiement CB |
| pending_bank_transfer | En attente de virement bancaire |

---

## Licenses

Le système de licenses (`licenses` table) permet d'activer des fonctionnalités spécifiques par organisation, indépendamment du plan Stripe.

---

## Taux de commission

La colonne `subscriptions.commission_rate` (DECIMAL 5,4) permet de stocker un taux de commission Xpeditis par organisation (pour tracking interne).

---

## Guide de configuration initial

Voir [../deployment/STRIPE_SETUP.md](../deployment/STRIPE_SETUP.md) pour la configuration complète de Stripe (création des products/prices, webhooks, etc.).