For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /fr/docs/modules/billing-configuration.md (or send Accept: text/markdown).
Configuration Stripe et webhooks
Reliez les abonnements web aux droits d’accès détenus par le serveur.
Configuration et paramètres
Avant toute étape, lisez Avant de commencer et Principes de base du terminal. Ces instructions supposent que vous avez ouvert le monorepo supastack complet dans VS Code ; sa racine package.json marque la racine du référentiel. Dans les commandes pnpm, un package d'espace de travail est une application ou un dossier de code partagé ; dans le produit, un espace de travail est le conteneur de données et la limite de sécurité d'une équipe. corepack pnpm --filter ... sélectionne un package dans le monorepo tandis que les commandes sont exécutées à partir de sa racine. Si vous avez ouvert uniquement un dossier mobile ou de bureau synchronisé, il ne contient pas le backend Web, la configuration Docker ou les scripts racine : exécutez le backend à partir de ce monorepo ou d'un serveur hébergé accessible et utilisez les propres scripts du dossier de plateforme. Une variable d'environnement est un paramètre nommé stocké dans un fichier .env local ou dans votre tableau de bord d'hébergement ; redémarrez l'application concernée après l'avoir modifiée et conservez les secrets du serveur en dehors des valeurs NEXT_PUBLIC_ et EXPO_PUBLIC_.
1. Ouvrez apps/web/.env.local et conservez BILLING_PROVIDER=local tout en apprenant l'écran de paiement.
2. Pour une véritable intégration, créez des produits en mode test chez un seul fournisseur, puis ajoutez ses clés de serveur et son secret de webhook aux paramètres d'environnement privé de l'hébergeur Web. Un webhook est un message signé que le service de facturation envoie à votre application après le paiement, le renouvellement ou l'annulation ; le chemin du point de terminaison est répertorié dans l’exemple de code de ce guide.
3. Démarrez Web avec le corepack pnpm --filter @supastack/web dev et testez uniquement le bac à sable. Attendu : un webhook vérifié met à jour les droits de l'espace de travail connecté ; l'ouverture d'une page de paiement à elle seule n'accorde pas l'accès.
Utilisez des identifiants de sandbox ou de test pendant l’intégration. Configurez BILLING_PROVIDER et les secrets propres au fournisseur, réservés au serveur : stripe → STRIPE_SECRET_KEY, STRIPE_PRICE_ID, STRIPE_WEBHOOK_SECRET ; lemonsqueezy → LEMONSQUEEZY_API_KEY, LEMONSQUEEZY_STORE_ID, LEMONSQUEEZY_VARIANT_ID, LEMONSQUEEZY_WEBHOOK_SECRET ; creem → CREEM_API_KEY, CREEM_PRODUCT_ID, CREEM_WEBHOOK_SECRET (CREEM_TEST_MODE=true pour la sandbox) ; polar → POLAR_ACCESS_TOKEN, POLAR_PRODUCT_ID, POLAR_WEBHOOK_SECRET (POLAR_SERVER) ; whop → WHOP_API_KEY, WHOP_PLAN_ID, WHOP_WEBHOOK_SECRET ; paddle → PADDLE_API_KEY, PADDLE_PRICE_ID, PADDLE_WEBHOOK_SECRET (PADDLE_ENVIRONMENT) ; dodo → DODO_PAYMENTS_API_KEY, DODO_PRODUCT_ID, DODO_PAYMENTS_WEBHOOK_KEY (DODO_PAYMENTS_ENVIRONMENT) ; paypal → PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_PLAN_ID, PAYPAL_WEBHOOK_ID (PAYPAL_ENVIRONMENT). Le tarif ou produit doit correspondre à l’abonnement récurrent souhaité.
Webhook endpoint: /api/billing/webhook (stripe), /api/billing/webhook/lemonsqueezy, /api/billing/webhook/creem, /api/billing/webhook/polar, /api/billing/webhook/whop, /api/billing/webhook/paddle, /api/billing/webhook/dodo, /api/billing/webhook/paypal
Checkout endpoint: /api/billing/checkout
Portal endpoint: /api/billing/portalCommandes à copier
Suivez les commentaires pour voir dans quel dossier une commande s'exécute. Si deux terminaux sont étiquetés, ouvrez deux fenêtres de terminal et laissez la première commande s'exécuter pendant que vous utilisez la seconde.
corepack pnpm --filter @supastack/web devProcessus d’implémentation
Lors de la configuration du point de terminaison webhook, suivez la liste des événements du cycle de vie dans docs/real-provider-smoke.md. La vérification de signature exige le secret webhook correspondant au point de terminaison. Une redirection vers le paiement ne doit jamais accorder l’accès à elle seule.
Le droit d’accès vérifié à la frontière de l’action serveur détermine si une opération payante est autorisée. Traitez les événements répétés sans effet indésirable et associez les enregistrements client et abonnement au bon espace de travail. Le paiement web reste distinct des achats natifs.
La clé accordée par une offre est un terme produit partagé entre les surfaces : ProductPlan.entitlement dans src/product-plans.ts déclare la clé machine en minuscules écrite dans le registre tant que l’offre est payée (le kit fournit 'ai.reference-task' sur pro et lifetime ; src/billing-runtime.ts la transmet au BFF). C’est cette même clé que le champ required_entitlement d’une entrée CMS et la prop entitlementKey du composant EntitlementGate comparent par égalité — une entrée protégée par 'ai.reference-task' se déverrouille pour tout espace de travail disposant de ce droit, tandis qu’une clé qu’aucune offre n’accorde reste verrouillée pour tous.
Vérification et dépannage
Si un webhook est rejeté, comparez le bac à sable URL exact et le secret de signature dans le tableau de bord du fournisseur avec les paramètres du serveur, et vérifiez si ce fournisseur exige le transfert des demandes vers localhost. Si le paiement fonctionne mais que l'accès reste verrouillé, inspectez le résultat du webhook et la clé d'autorisation sur le plan. Ne testez jamais avec des informations d'identification de paiement en direct tout en suivant ce guide local.
Dans la sandbox, testez l’activation, les mises à jour, l’annulation, les signatures invalides et les événements répétés. Examinez l’état d’accès persistant après le traitement. La création d’une session de paiement sans consommation prouve uniquement la connectivité, pas l’exécution complète du cycle de vie.