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/web/stripe-payments.md (or send Accept: text/markdown).
Ajouter les paiements Stripe
Créez un compte Stripe gratuit, un produit avec un prix récurrent, une clé secrète et le webhook signé qui accorde les entitlements après le checkout.
Parcours pas à pas pour débuter
Prérequis : l'app qui tourne en local (En ligne en 5 minutes) et une base de données migrée pour de vrais comptes (Configurer la base de données). Il vous faut une adresse e-mail pour le compte Stripe — ni carte ni débits. Tout dans ce guide se passe en mode test : fausse monnaie, numéros de carte de test, essais illimités avant le passage en production.
Quelques termes : le mode test est le sandbox de Stripe — le commutateur Test mode du tableau de bord garde chaque clé, produit et paiement fictif jusqu'à ce que vous le désactiviez. Une secret key (sk_test_…) est le mot de passe de votre serveur auprès de Stripe. Un produit avec un prix est ce que les clients achètent ; un price id (price_…) le nomme dans le code. Un webhook, c'est Stripe qui appelle votre serveur quand un paiement réussit ou qu'un abonnement change, et le signing secret (whsec_…) prouve que l'appel vient vraiment de Stripe.
Ce que vous créez : un compte Stripe, un produit avec un prix récurrent, une clé d'API secrète et un endpoint de webhook — environ vingt minutes. Stripe héberge la page de checkout elle-même ; le kit crée la session côté serveur et redirige, donc aucune clé publishable de navigateur n'est nécessaire.
Gardez la portée en tête : ce guide vend uniquement des abonnements web. Les achats dans l'app iOS/Android doivent passer par la facturation d'Apple et de Google — jamais par Stripe Checkout — c'est pourquoi le mobile utilise RevenueCat à la place.
Créer le compte Stripe
1. Ouvrez stripe.com → Start now et inscrivez-vous avec votre e-mail.
2. L'onboarding pose des questions sur votre activité — en mode test vous pouvez ignorer chaque question et quand même utiliser tout le sandbox ; ne terminez l'activation qu'avant d'encaisser de vrais paiements.
Attendu : vous arrivez sur le tableau de bord avec le commutateur Test mode visible dans l'en-tête. Laissez-le activé pour tout ce qui suit — les clés live iront plus tard dans votre coffre de secrets de production, jamais dans un fichier env d'ordinateur portable.
Copier les clés d'API
1. Dans le tableau de bord, ouvrez Developers → API keys.
2. Vous voyez deux clés de test : une Publishable key pk_test_… et une Secret key masquée. Cliquez sur Reveal test key à côté du secret et copiez la valeur sk_test_….
Le kit n'a besoin que de la secret key : les sessions de checkout sont créées sur le serveur et l'utilisateur est redirigé vers la page hébergée de Stripe, donc aucune publishable key n'atterrit dans les variables env. Si un produit que vous construirez plus tard ajoute Stripe.js, vous utiliseriez la publishable key côté client ; le flux de facturation du kit ne le fait pas.
La clé sk_test_… est un identifiant complet pour le compte sandbox : elle vit dans apps/web/.env.local ou dans un coffre de secrets, jamais dans des variables NEXT_PUBLIC_/EXPO_PUBLIC_ et jamais dans Git.
Créer le produit et le prix
1. Ouvrez Product catalog → Add product.
2. Nommez-le d'après votre plan — Pro correspond au plan livré du kit — donnez-lui un prix et choisissez Recurring (mensuel, par exemple) : le checkout du kit crée des sessions en mode abonnement, qui exigent un prix récurrent et non un prix unique.
3. Enregistrez, ouvrez le produit et copiez le price id — il commence par price_… (pas prod_…, qui est l'id du produit).
Le plan pro livré affiche déjà un commutateur Monthly/Yearly : le mensuel paie avec STRIPE_PRICE_ID, et l'option annuelle a besoin d'un second prix récurrent dans STRIPE_PRICE_ID_PRO_YEARLY — sans lui, un checkout annuel échoue avec price-unconfigured. Changez les noms de plans, les montants et ce qu'accorde un achat dans apps/web/src/product-plans.ts — Stripe stocke le côté argent, le fichier de plans stocke le côté entitlement.
Ajouter l'endpoint de webhook
Le webhook est ce qui accorde réellement l'accès : le kit n'active l'entitlement qu'après l'arrivée d'un événement Stripe signé, donc une redirection de checkout à elle seule ne prouve rien.
1. Ouvrez Developers → Webhooks → Add endpoint.
2. Endpoint URL : votre URL publique plus /api/billing/webhook — par exemple https://yourdomain.com/api/billing/webhook. Les autres fournisseurs de facturation ont leur propre chemin sous ce répertoire ; le receveur de Stripe vit à la racine.
3. Sous Select events, choisissez les événements que le kit gère : checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, invoice.paid, invoice.payment_failed, customer.subscription.created, customer.subscription.updated et customer.subscription.deleted.
4. Créez l'endpoint, ouvrez sa page, cliquez sur Reveal sous Signing secret et copiez la valeur whsec_… — chaque endpoint a son propre secret.
Le développement local ne peut pas recevoir les serveurs de Stripe, donc utilisez la Stripe CLI à la place : stripe login une fois, puis stripe listen --forward-to localhost:3000/api/billing/webhook dans un second terminal. Elle imprime un whsec_… temporaire — c'est cette valeur, pas celle du tableau de bord, qui va dans .env.local pendant que stripe listen tourne.
Ajouter les valeurs à l'app
Renseignez les lignes ci-dessous dans apps/web/.env.local. BILLING_PROVIDER=stripe sélectionne l'adaptateur ; les trois autres sont la clé, le prix et le signing secret. Activer le fournisseur alors que l'un d'eux manque fait échouer le démarrage et nomme la variable.
Les trois valeurs STRIPE_* restent côté serveur — jamais NEXT_PUBLIC_/EXPO_PUBLIC_, jamais commitées ; la production les reçoit via le gestionnaire de secrets de l'hébergeur (le guide de déploiement couvre Secret Manager). Redémarrez le serveur de dev après modification.
# apps/web/.env.local
BILLING_PROVIDER=stripe
STRIPE_SECRET_KEY=sk_test_…
STRIPE_PRICE_ID=price_…
STRIPE_WEBHOOK_SECRET=whsec_… # `stripe listen` value locally; endpoint signing secret in production
# STRIPE_PRICE_ID_PRO_YEARLY=price_… # required for the shipped Yearly toggleVérifier et dépanner
Lancez stripe listen --forward-to localhost:3000/api/billing/webhook et laissez-le tourner, redémarrez le serveur de dev, puis ouvrez /billing, choisissez le plan Pro et terminez le checkout hébergé de Stripe avec la carte de test 4242 4242 4242 4242, une expiration future quelconque et un CVC quelconque.
Attendu : l'app revient sur /billing?checkout=success et l'entitlement du workspace passe à actif — le terminal de listen consigne les événements livrés, et Developers → Webhooks → votre endpoint dans le tableau de bord affiche des livraisons vertes.
Pour exercer le receveur sans cliquer dans le checkout, stripe trigger checkout.session.completed envoie un événement synthétique à travers le redirecteur de listen.
Échecs fréquents : un 400 à chaque livraison signifie que le signing secret ne correspond pas à cet endpoint — recopiez le whsec_… du bon endpoint et mettez à jour l'env ; des non-opérations silencieuses signifient que BILLING_PROVIDER vaut encore local ; et des clés sk_live_ mélangées dans un montage de test signifient que vous avez copié les clés du mauvais mode — gardez test et live strictement séparés.
Le kit livre le même adaptateur à contrat unique pour Lemon Squeezy, Creem, Polar, Whop, Paddle, Dodo et PayPal — même flux, console et noms d'env différents — et les achats mobiles restent sur RevenueCat, pas Stripe.