David/xpeditis2.0

Fork 0

David 5c7834c7e4 fix licensing

2026-01-20 11:28:54 +01:00

6.3 KiB

Raw Blame History

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

Allez dans Developers > Webhooks
Cliquez sur Add endpoint
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
Cliquez sur Add endpoint
Notez le Webhook signing secret (format: whsec_xxxxx)

3.2 Test Local avec Stripe CLI

Pour tester les webhooks en local :

# 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 :

# 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).

Allez dans Settings > Billing > Customer portal
Activez les options souhaitées :
- Allow customers to update their payment methods
- Allow customers to update subscriptions
- Allow customers to cancel subscriptions
- Show invoice history
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

Lancez le backend et le frontend
Connectez-vous en tant qu'ADMIN
Allez dans Settings > Subscription
Cliquez sur "Upgrade" sur un plan payant
Utilisez la carte de test 4242 4242 4242 4242
Vérifiez que le plan est mis à jour dans la base de données
Vérifiez que les licences sont correctement comptées

10. Commandes utiles

# 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

6.3 KiB Raw Blame History