111 lines
3.0 KiB
Markdown
111 lines
3.0 KiB
Markdown
# 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.).
|