220 lines
6.3 KiB
Markdown
220 lines
6.3 KiB
Markdown
# Configuration Stripe pour Xpeditis
|
|
|
|
Ce guide explique comment configurer Stripe pour le système de licences et d'abonnements.
|
|
|
|
## 1. Prérequis
|
|
|
|
- Compte Stripe (https://dashboard.stripe.com)
|
|
- Accès aux clés API Stripe
|
|
|
|
## 2. Configuration du Dashboard Stripe
|
|
|
|
### 2.1 Créer les Produits
|
|
|
|
Dans le Dashboard Stripe, allez dans **Products** et créez les produits suivants :
|
|
|
|
| Produit | Description |
|
|
|---------|-------------|
|
|
| **Xpeditis Starter** | Plan Starter - Jusqu'à 5 utilisateurs |
|
|
| **Xpeditis Pro** | Plan Pro - Jusqu'à 20 utilisateurs |
|
|
| **Xpeditis Enterprise** | Plan Enterprise - Utilisateurs illimités |
|
|
|
|
### 2.2 Créer les Prix
|
|
|
|
Pour chaque produit, créez 2 prix (mensuel et annuel) :
|
|
|
|
#### Starter
|
|
| Type | Prix | Récurrence |
|
|
|------|------|------------|
|
|
| Mensuel | 49 EUR | /mois |
|
|
| Annuel | 470 EUR | /an (~20% de réduction) |
|
|
|
|
#### Pro
|
|
| Type | Prix | Récurrence |
|
|
|------|------|------------|
|
|
| Mensuel | 149 EUR | /mois |
|
|
| Annuel | 1430 EUR | /an (~20% de réduction) |
|
|
|
|
#### Enterprise
|
|
| Type | Prix | Récurrence |
|
|
|------|------|------------|
|
|
| Mensuel | Prix personnalisé | /mois |
|
|
| Annuel | Prix personnalisé | /an |
|
|
|
|
### 2.3 Récupérer les Price IDs
|
|
|
|
Après avoir créé les prix, notez les **Price IDs** (format: `price_xxxxx`) pour chaque prix.
|
|
|
|
## 3. Configuration du Webhook
|
|
|
|
### 3.1 Créer le Webhook Endpoint
|
|
|
|
1. Allez dans **Developers > Webhooks**
|
|
2. Cliquez sur **Add endpoint**
|
|
3. Configurez :
|
|
- **Endpoint URL**: `https://votre-domaine.com/api/v1/subscriptions/webhook`
|
|
- **Events to send**: Sélectionnez les événements suivants :
|
|
- `checkout.session.completed`
|
|
- `customer.subscription.created`
|
|
- `customer.subscription.updated`
|
|
- `customer.subscription.deleted`
|
|
- `invoice.payment_failed`
|
|
|
|
4. Cliquez sur **Add endpoint**
|
|
5. Notez le **Webhook signing secret** (format: `whsec_xxxxx`)
|
|
|
|
### 3.2 Test Local avec Stripe CLI
|
|
|
|
Pour tester les webhooks en local :
|
|
|
|
```bash
|
|
# Installer Stripe CLI
|
|
brew install stripe/stripe-cli/stripe
|
|
|
|
# Se connecter à Stripe
|
|
stripe login
|
|
|
|
# Écouter les webhooks et les transférer en local
|
|
stripe listen --forward-to localhost:4000/api/v1/subscriptions/webhook
|
|
|
|
# Le CLI affichera le webhook secret à utiliser localement
|
|
# > Ready! Your webhook signing secret is whsec_xxxxx
|
|
```
|
|
|
|
## 4. Variables d'environnement
|
|
|
|
Ajoutez ces variables dans votre fichier `.env` du backend :
|
|
|
|
```bash
|
|
# Clés API Stripe
|
|
STRIPE_SECRET_KEY=sk_test_xxxxx # Clé secrète (test ou live)
|
|
STRIPE_WEBHOOK_SECRET=whsec_xxxxx # Secret du webhook
|
|
|
|
# Price IDs (créés dans le Dashboard)
|
|
STRIPE_STARTER_MONTHLY_PRICE_ID=price_xxxxx
|
|
STRIPE_STARTER_YEARLY_PRICE_ID=price_xxxxx
|
|
STRIPE_PRO_MONTHLY_PRICE_ID=price_xxxxx
|
|
STRIPE_PRO_YEARLY_PRICE_ID=price_xxxxx
|
|
STRIPE_ENTERPRISE_MONTHLY_PRICE_ID=price_xxxxx
|
|
STRIPE_ENTERPRISE_YEARLY_PRICE_ID=price_xxxxx
|
|
|
|
# URL Frontend (pour les redirections)
|
|
FRONTEND_URL=http://localhost:3000
|
|
```
|
|
|
|
## 5. Configurer le Customer Portal
|
|
|
|
Le Customer Portal permet aux clients de gérer leur abonnement (changer de plan, annuler, mettre à jour le paiement).
|
|
|
|
1. Allez dans **Settings > Billing > Customer portal**
|
|
2. Activez les options souhaitées :
|
|
- [x] Allow customers to update their payment methods
|
|
- [x] Allow customers to update subscriptions
|
|
- [x] Allow customers to cancel subscriptions
|
|
- [x] Show invoice history
|
|
|
|
3. Configurez les produits autorisés dans le portal
|
|
|
|
## 6. Mode Test vs Production
|
|
|
|
### Mode Test (Développement)
|
|
- Utilisez `sk_test_xxxxx` comme clé secrète
|
|
- Les paiements ne sont pas réels
|
|
- Utilisez les cartes de test Stripe :
|
|
- Succès: `4242 4242 4242 4242`
|
|
- Échec: `4000 0000 0000 0002`
|
|
- 3D Secure: `4000 0025 0000 3155`
|
|
|
|
### Mode Production
|
|
- Utilisez `sk_live_xxxxx` comme clé secrète
|
|
- Activez le mode live dans le Dashboard
|
|
- Assurez-vous d'avoir complété la vérification de compte
|
|
|
|
## 7. Flux d'abonnement
|
|
|
|
```
|
|
┌─────────────────┐
|
|
│ Page Subscription│
|
|
│ (Frontend) │
|
|
└────────┬────────┘
|
|
│ Clic "Upgrade"
|
|
▼
|
|
┌─────────────────┐
|
|
│ POST /checkout │
|
|
│ (Backend) │
|
|
└────────┬────────┘
|
|
│ Crée Checkout Session
|
|
▼
|
|
┌─────────────────┐
|
|
│ Stripe Checkout │
|
|
│ (Stripe) │
|
|
└────────┬────────┘
|
|
│ Paiement réussi
|
|
▼
|
|
┌─────────────────┐
|
|
│ Webhook │
|
|
│ checkout. │
|
|
│ session.completed│
|
|
└────────┬────────┘
|
|
│ Met à jour la subscription
|
|
▼
|
|
┌─────────────────┐
|
|
│ Base de données │
|
|
│ (PostgreSQL) │
|
|
└─────────────────┘
|
|
```
|
|
|
|
## 8. Gestion des erreurs
|
|
|
|
### Paiement échoué
|
|
- Le webhook `invoice.payment_failed` est déclenché
|
|
- L'abonnement passe en statut `PAST_DUE`
|
|
- L'utilisateur est informé et peut mettre à jour son moyen de paiement
|
|
|
|
### Annulation
|
|
- Via le Customer Portal ou l'API
|
|
- L'abonnement reste actif jusqu'à la fin de la période
|
|
- À la fin de la période, le webhook `customer.subscription.deleted` est déclenché
|
|
- L'organisation repasse au plan FREE
|
|
|
|
## 9. Vérification
|
|
|
|
### Checklist de configuration
|
|
|
|
- [ ] Produits créés dans Stripe Dashboard
|
|
- [ ] Prix créés (mensuel + annuel pour chaque plan)
|
|
- [ ] Webhook endpoint configuré
|
|
- [ ] Customer Portal configuré
|
|
- [ ] Variables d'environnement ajoutées au `.env`
|
|
- [ ] Test avec Stripe CLI en local
|
|
- [ ] Test d'un paiement complet (checkout → webhook)
|
|
|
|
### Test manuel
|
|
|
|
1. Lancez le backend et le frontend
|
|
2. Connectez-vous en tant qu'ADMIN
|
|
3. Allez dans Settings > Subscription
|
|
4. Cliquez sur "Upgrade" sur un plan payant
|
|
5. Utilisez la carte de test `4242 4242 4242 4242`
|
|
6. Vérifiez que le plan est mis à jour dans la base de données
|
|
7. Vérifiez que les licences sont correctement comptées
|
|
|
|
## 10. Commandes utiles
|
|
|
|
```bash
|
|
# Voir les webhooks reçus
|
|
stripe events list --limit 10
|
|
|
|
# Déclencher un webhook manuellement
|
|
stripe trigger checkout.session.completed
|
|
|
|
# Voir les logs
|
|
stripe logs tail
|
|
```
|
|
|
|
## Support
|
|
|
|
Pour toute question sur Stripe :
|
|
- Documentation Stripe : https://stripe.com/docs
|
|
- Support Stripe : https://support.stripe.com
|