Intégration Stripe
Stripe gère la facturation et les abonnements des organisations clientes GovernIA : checkout, portail client, webhooks, et suivi des paiements.
Ce que fait l'intégration
| Fonctionnalité | Description |
|---|---|
| Abonnements | Création et gestion des plans (MONTHLY / YEARLY) |
| Checkout | Session de paiement hébergée Stripe avec codes promo |
| Portail client | Interface Stripe self-service pour changer de plan, mettre à jour la CB, télécharger les factures |
| Factures | Liste des factures avec téléchargement PDF |
| Webhooks | Synchronisation automatique des états d'abonnement |
| Dashboard admin | Vue des tenants, override de statut, gestion des plans |
Prérequis
Un compte Stripe sur dashboard.stripe.com avec :
- Les plans/prix créés dans Stripe (un price ID par offre)
- Un endpoint webhook configuré
- La clé secrète et la clé webhook récupérées
Configuration
Depuis Backoffice → Paramètres → Stripe, renseignez la clé secrète et le webhook secret. La facturation reste désactivée tant que la clé n'est pas configurée.
Champs disponibles
| Champ | Description |
|---|---|
| Clé secrète | sk_live_... en prod, sk_test_... en dev |
| Webhook Secret | whsec_... — requis pour valider les événements Stripe entrants |
| Entité de facturation | Nom légal affiché sur les factures |
| Service | Libellé de la ligne de facturation |
Configuration du webhook Stripe
1. Créer l'endpoint
Dans le dashboard Stripe :
Developers → Webhooks → Add endpoint
| Champ | Valeur |
|---|---|
| URL | https://api.governia.eu/billing/webhook (prod) ou https://api-dev.governia.eu/billing/webhook (dev) |
| Version | 2026-01-28 |
2. Sélectionner les événements
Activez uniquement ces événements :
| Événement | Effet dans GovernIA |
|---|---|
checkout.session.completed | Active l'abonnement après paiement |
customer.subscription.updated | Met à jour le plan, cycle, statut |
customer.subscription.deleted | Passe le statut à CANCELED |
invoice.payment_succeeded | Confirme le paiement → statut ACTIVE |
invoice.payment_failed | Marque l'abonnement PAST_DUE |
3. Récupérer le Webhook Secret
Après création de l'endpoint, Stripe affiche le Signing secret (whsec_...). Copiez-le dans Paramètres → Stripe → Webhook Secret.
États d'abonnement
| Statut | Description |
|---|---|
TRIALING | Période d'essai (14 jours par défaut) |
ACTIVE | Abonnement actif, paiement à jour |
PAST_DUE | Dernier paiement échoué |
CANCELED | Abonnement résilié |
PAUSED | Abonnement suspendu (override admin) |
Redirections après checkout
| Action | Redirection |
|---|---|
| Paiement réussi | {CLIENT_APP_URL}/suite/billing?checkout=success |
| Paiement annulé | {CLIENT_APP_URL}/suite/billing?checkout=cancel |
| Retour portail | {CLIENT_APP_URL}/suite/billing |
Tester en développement
Utilisez les cartes de test Stripe :
| Carte | Comportement |
|---|---|
4242 4242 4242 4242 | Paiement réussi |
4000 0000 0000 9995 | Paiement refusé |
4000 0025 0000 3155 | Authentification 3DS requise |
Pour tester les webhooks en local, utilisez la Stripe CLI :
bash
stripe listen --forward-to localhost:4000/billing/webhookDépannage
| Problème | Cause probable | Solution |
|---|---|---|
| La facturation n'est pas activée | Clé secrète absente ou invalide | Vérifier dans Paramètres → Stripe que la clé commence par sk_ |
| Webhooks non reçus | Endpoint mal configuré ou secret incorrect | Vérifier l'URL du webhook dans Stripe et le Webhook Secret dans Paramètres |
| Abonnement bloqué sur TRIALING | Webhook checkout.session.completed non reçu | Vérifier les logs webhook dans le dashboard Stripe |
| Erreur 400 sur le webhook | Signature invalide | Vérifier que le Webhook Secret correspond à l'endpoint actif |