Mettre en place la facturation de vos utilisateurs

Activez les abonnements et les paiements pour les organisations qui utilisent votre plateforme kuploy-cloud. Ce guide vous accompagne dans la connexion de Stripe et la création des offres auxquelles vos utilisateurs finaux souscriront.

Offres d'instance et offres de plateforme

Les offres que vous configurez ici sont des offres d'instance : les abonnements que vos clients, les organisations, vous règlent. Elles sont distinctes de votre offre de plateforme chez kuploy.app.

Vous en maîtrisez les tarifs, les limites et les noms.

Un seul point d'encaissement

Tous les paiements — cartes Stripe, Apple Pay et Google Pay, mobile money — passent par la passerelle de paiement, à partir de l'offre Business, qui s'appuie sur ePay. Ce guide s'arrête à la création d'un compte Stripe et à la définition de vos offres ; le branchement des clés et du webhook se fait une fois pour toutes sur la page d'administration de la passerelle, et non canal par canal.

1. Créer un compte Stripe

Si vous n'en avez pas encore :

1. Rendez-vous sur stripe.com et cliquez sur Start now
2. Saisissez votre adresse e-mail et créez un mot de passe
3. Validez votre adresse
4. Complétez la vérification d'entreprise — elle peut attendre, pour des tests

Le mode test

Stripe propose un mode test pour le développement. Activez « Test mode » en haut à droite du tableau de bord Stripe. Ce mode utilise de l'argent fictif et des numéros de carte de test : parfait pour la mise en place et les essais.

2. Récupérer vos clés d'API

1. Dans le tableau de bord Stripe, cliquez sur Developers, dans la barre latérale
2. Cliquez sur API keys
3. Deux clés s'affichent :
   • la clé publiable (pk_test_... ou pk_live_...) — sans danger si elle est exposée ;
   • la clé secrète (sk_test_... ou sk_live_...) — à garder privée.
4. Cliquez sur Reveal test key pour copier votre clé secrète

attention

Ne partagez jamais votre clé secrète. Ne la versionnez jamais. Ne la saisissez que dans des réglages sécurisés.

3. Les produits Stripe sont créés automatiquement

Vous n'avez pas à créer de produits ni de prix dans Stripe à la main. Lorsque vous enregistrez une offre tarifée à /admin/plans, kuploy-cloud crée — ou met à jour — le produit et le prix Stripe correspondants sur votre propre compte, avec le tarif que vous venez de saisir.

/admin/plans (vous)                   Stripe (votre compte)
┌───────────────────────┐             ┌─────────────────────────────┐
│ identifiant : "pro"   │             │  Crée/met à jour le produit │
│ prix : 2000           │─à l'enreg.─►│  Crée/met à jour le prix    │
│ devise : "cad"        │             │  (archive l'ancien prix)    │
│ périodicité : mensuel │             └─────────────────────────────┘
└───────────────────────┘

Modifiez le tarif d'une offre et l'enregistrement suivant met à jour le prix Stripe. Les abonnements existants ne sont pas modifiés rétroactivement : seuls les nouveaux paiements utilisent le tarif à jour.

Une offre gratuite n'a pas de prix Stripe

Une offre à 0 n'ayant rien à facturer, aucun produit ni prix Stripe n'est créé pour elle. C'est normalement votre offre par défaut, celle où aboutissent les nouvelles organisations sans aucune étape de paiement.

4. Connecter Stripe via la passerelle de paiement

Vos identifiants Stripe vivent sur un enregistrement de prestataire au sein de votre déploiement epay-gateway, et non dans un écran de réglages propre à kuploy-cloud. Cela garantit une source de vérité unique pour tous les canaux de paiement.

Suivez le guide de mise en place de la passerelle de paiement pour :

• connecter kuploy-cloud à votre déploiement epay-gateway ;
• créer sur la passerelle un enregistrement de prestataire Stripe, avec votre clé secrète (sk_test_... ou sk_live_...) et votre secret de signature de webhook (whsec_...) ;
• faire pointer le point de réception de webhook Stripe vers la passerelle — et non directement vers kuploy-cloud : l'ancien point /api/webhooks/stripe de kuploy-cloud a été supprimé lors de la bascule.

Une fois la passerelle connectée, le panneau Admin → Payment Gateway affiche « configured », et les paiements d'offre, le portail de facturation et la liste des factures fonctionnent sans réglage supplémentaire.

5. Définir vos offres

Les offres vivent dans votre instance, à Admin → Plans (/admin/plans). Vous en fixez vous-même chaque nom, tarif, quota et fonctionnalité ; kuploy.app ne vous impose jamais de catalogue.

Une installation neuve ne contient que free et internal. De là, Suggest paid plans vous donne une échelle Starter / Growth / Business sous forme de brouillons masqués à retravailler, ou vous construisez chaque offre à la main.

Votre offre de plateforme est un plafond, non un modèle : une offre accordant plus que votre niveau kuploy.app ne permet est refusée à l'enregistrement, et une fonctionnalité n'atteint une organisation que si votre niveau de plateforme et l'offre de celle-ci l'accordent tous les deux.

Voir Gérer vos offres pour le détail complet : quotas, devise, niveau Internal, et ce que vous ne pouvez pas supprimer.

6. Vérifier vos offres

1. Dans kuploy-cloud, allez dans Admin → Plans
2. Vérifiez que chaque offre affiche le nom, le tarif et la devise attendus
3. Assurez-vous qu'une offre et une seule porte la mention Default : c'est là qu'aboutissent les nouvelles organisations
4. Les produits et les prix Stripe sont créés à l'enregistrement — aucun identifiant de prix à saisir à la main

7. Mettre en place les webhooks

Les webhooks Stripe transitent désormais de Stripe vers votre epay-gateway, puis vers kuploy-cloud, plutôt que directement vers kuploy-cloud. La mise en place complète est décrite dans le guide de la passerelle — voir Faire pointer vos webhooks.

En résumé :

1. Dans le tableau de bord Stripe, ajoutez un point de réception pointant vers votre epay-gateway :

   https://<hote-de-votre-passerelle>/api/webhooks/stripe/<codeMarchand>

2. Abonnez-vous aux événements d'abonnement et de facture (customer.subscription.*, invoice.payment_*).
3. Collez le secret de signature Stripe (whsec_...) dans l'enregistrement de prestataire Stripe de votre passerelle — et non dans kuploy-cloud. La passerelle vérifie puis relaie vers /api/webhooks/epay, côté kuploy-cloud.

8. Tester votre installation

Servez-vous des cartes de test Stripe pour vérifier que tout fonctionne :

Numéro de carte	Résultat
4242 4242 4242 4242	Paiement accepté
4000 0000 0000 0002	Carte refusée
4000 0000 0000 3220	Demande une authentification 3D Secure

Utilisez n'importe quelle date d'expiration future et n'importe quel cryptogramme à trois chiffres.

1. Créez un compte utilisateur de test
2. Allez dans Billing et choisissez une offre payante
3. Réglez avec une carte de test
4. Vérifiez que l'abonnement apparaît aussi bien dans kuploy-cloud que dans le tableau de bord Stripe

Attribuer une offre à la main (salariés, partenaires, comptes de test)

Certaines organisations de votre plateforme ne doivent pas être facturées par Stripe : vos salariés, vos partenaires, ou des comptes de test que vous créez vous-même. Pour celles-là, passez par Admin → Organizations & Plans, dans votre tableau de bord kuploy-cloud :

1. Recherchez l'organisation
2. Cliquez sur Change plan et choisissez une offre dans la liste
3. Enregistrez — l'organisation dispose désormais d'un abonnement « active » marqué Manual, avec une période de facturation de 30 jours, de sorte que les quotas de minutes de build repartent à une échéance prévisible

Les abonnements manuels portent une pastille Manual dans la liste des organisations. Leurs membres voient, sur la page de facturation, un message indiquant que leur offre est gérée par l'administrateur de la plateforme, à la place des boutons de paiement et de portail Stripe. Reset period fait repartir la période de 30 jours, et Cancel marque l'abonnement manuel comme résilié.

Les abonnements portés par Stripe sont en lecture seule ici

L'administration des organisations refuse de changer l'offre d'un abonnement porté par Stripe, afin d'éviter toute divergence entre la base de données et Stripe. Pour les modifier, passez par le tableau de bord Stripe : les webhooks répercuteront le changement.

Passer en production

Lorsque vous êtes prêt :

1. Terminez la vérification d'entreprise chez Stripe
2. Désactivez « Test mode » dans le tableau de bord Stripe
3. Remplacez la clé secrète Stripe et le secret de signature de webhook par leurs valeurs de production, sur l'enregistrement de prestataire Stripe de votre epay-gateway
4. Dans le tableau de bord Stripe, faites pointer le point de réception vers l'URL de production de votre epay-gateway — les points de réception des modes test et production sont distincts
5. Réenregistrez chaque offre tarifée à /admin/plans, pour que son produit et son prix soient créés sur le compte Stripe de production
6. Testez avec une vraie carte — vous pourrez rembourser immédiatement

kuploy-cloud n'a lui-même aucune clé Stripe à remplacer : la passerelle est le seul endroit où vivent ces identifiants.

---

Référence technique

Pour un déploiement Kubernetes, les seules variables d'environnement liées à Stripe vivent sur votre déploiement epay-gateway, et non sur kuploy-cloud. Voir admin/.env.example dans le dépôt de la passerelle pour la liste complète.

kuploy-cloud n'a besoin que des informations de connexion à la passerelle : URL, clé d'administration, code marchand et clé marchand. Elles se renseignent depuis Admin → Payment Gateway ; pour une installation Kubernetes sans interface, les mêmes quatre valeurs sont acceptées comme variables d'environnement :

Variable	Description
EPAY_GATEWAY_URL	L'URL publique de votre déploiement epay-gateway
EPAY_GATEWAY_ADMIN_KEY	Le jeton que kuploy-cloud présente pour appeler l'API de gestion de la passerelle
EPAY_MERCHANT_CODE	L'identifiant marchand de l'exploitant au sein de la passerelle
EPAY_MERCHANT_KEY	Le secret HMAC qui sert à vérifier les webhooks relayés

Appliquez-les comme d'habitude :

echo -n "votre_cle_admin" | base64
kubectl patch secret kuploy-secrets -n kuploy \
  -p '{"data":{"EPAY_GATEWAY_ADMIN_KEY":"<valeur-base64>"}}'
kubectl rollout restart deployment/kuploy -n kuploy

Les migrations de base de données

Les évolutions de schéma s'exécutent automatiquement au démarrage d'un nouveau conteneur, avant qu'il n'accepte du trafic. Vous n'avez aucune commande de migration à lancer, ni la moindre étape manuelle lors d'une mise à niveau — voir Passer à l'édition Cloud.

---

Dépannage

Le paiement échoue

1. Ouvrez Admin → Payment Gateway dans kuploy-cloud et cliquez sur Test Connection — une coche verte confirme que kuploy-cloud joint la passerelle avec la clé d'administration enregistrée.
2. Dans l'administration de votre epay-gateway, vérifiez que l'enregistrement de prestataire Stripe porte la bonne clé secrète pour le mode en cours — test ou production.
3. Vérifiez que la synchronisation des offres a abouti et que les prix Stripe ont bien été créés :

   kubectl logs -n kuploy -l app.kubernetes.io/name=kuploy | grep -i "stripe.*price"

Les webhooks n'arrivent pas

1. Vérifiez que le point de réception du tableau de bord Stripe vise bien votre epay-gateway (https://<passerelle>/api/webhooks/stripe/<codeMarchand>), et non kuploy-cloud.
2. Sur l'enregistrement de prestataire Stripe de la passerelle, l'apiSecret doit correspondre au secret de signature de ce point de réception dans le tableau de bord Stripe.
3. Le point d'entrée de kuploy-cloud est /api/webhooks/epay : consultez ses logs à la recherche d'erreurs de signature ou de vérification.
4. Consultez les journaux de livraison côté Stripe : tableau de bord Stripe → Developers → Webhooks → sélectionnez le point de réception.

Les offres n'apparaissent pas

Votre catalogue d'offres est local à votre instance : rien n'arrive de kuploy.app, un problème de synchronisation n'en est donc jamais la cause. Dans Admin → Plans, vérifiez que :

1. l'offre existe bel et bien. Une installation neuve ne contient que free et internal tant que vous n'en ajoutez pas — Suggest paid plans fournit une échelle de départ ;
2. elle est Active. Une offre inactive conserve ses abonnés mais disparaît des nouvelles inscriptions ;
3. elle est Public. Une offre non publique disparaît de /pricing et du sélecteur de changement d'offre ; vous pouvez toujours y rattacher une organisation depuis Admin → Organizations & Plans ;
4. une offre et une seule porte la mention Default, faute de quoi les nouvelles organisations n'ont nulle part où aboutir.