← Retour au blog
TutorialPublié 2026-04-28· 14 min de lecture

Abonnements Stripe sur Next.js : guide complet

WangNan, author at Uncorne
Publié par Uncorne · Mis à jour 2026-11-12

Voici le chemin le plus court vers les abonnements Stripe dans Next.js qui ne cassera pas en production. Quatre pièces mobiles, sans fluff — avec les détails de vérification que la plupart des guides passent sous silence.

Les intégrations d'abonnement échouent rarement sur le chemin nominal. Un client clique sur s'abonner, une Checkout Session est créée, un webhook se déclenche, un drapeau bascule dans la base. Cela fonctionne dans chaque tutoriel. Ce qui échoue, c'est tout autour : un webhook forgé accepté avec 200, un événement rejoué appliqué deux fois, un offre qui ne revient jamais en arrière après annulation, ou une clé secrète expédiée par accident dans le navigateur. Ce guide couvre la boucle entière, y compris les échecs.

Les quatre pièces mobiles d'un abonnement Stripe dans Next.js
Les quatre pièces mobiles d'un abonnement Stripe dans Next.js

Prérequis

Trois choses avant d'écrire du code :

  • Un projet Next.js 15 avec l'App Router. Si vous démarrez de zéro, la documentation App Router fait référence.
  • Un compte Stripe en mode test, avec votre clé secrète et un secret de signature de webhook.
  • Une table users avec une colonne plan, ou une table subscriptions séparée, que votre serveur peut écrire.

Définissez les variables d'environnement une fois et gardez les identifiants de test et de production dans des environnements distincts :

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_ID_PRO=price_...
NEXT_PUBLIC_APP_URL=http://localhost:3000

Ne préfixez jamais un secret Stripe par NEXT_PUBLIC_. Tout ce qui porte ce préfixe est intégré au bundle navigateur et est public par définition. Une clé secrète côté client n'est pas un raccourci, c'est un identifiant publié.

Étape 1 : Créer le produit et le prix

Dans le tableau de bord Stripe, créez un Product avec un Price récurrent — par exemple Pro à 12 USD par mois. Copiez le Price ID dans STRIPE_PRICE_ID_PRO. Ne le codez jamais en dur dans le source. Les Price ID diffèrent entre test et production, donc un prix de test codé en dur est un bug de production silencieux : le checkout semble correct mais le montant ou la devise est faux.

Gardez une courte correspondance entre vos noms d'offres et les Price ID, pour que la tarification régionale ou par palier soit une modification de données plutôt que de code. Modélisez les offres comme des données, pas comme des branches dans le code. Un objet PLANS avec id, priceId et entitlements permet au contrôle d'accès de vérifier une capacité comme canExport ou seats au lieu d'un nom d'offre ; renommer un palier ne touche alors aucune route. Cela rend aussi la facturation annuelle simple : ajoutez un second Price ID à la même offre et laissez la route de checkout le choisir depuis une requête validée.

Un produit du tableau de bord Stripe avec un prix récurrent et son Price ID
Un produit du tableau de bord Stripe avec un prix récurrent et son Price ID

Étape 2 : Installer et configurer le SDK

Installez le SDK serveur officiel avec npm install stripe. Instanciez un client au niveau du module pour que la configuration n'ait lieu qu'une fois :

import Stripe from "stripe";

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2025-02-24.acacia",
});

Épinglez la version de l'API dans le code plutôt que de la laisser flotter. Quand Stripe sort une nouvelle version, vous voulez lire le changelog et l'adopter délibérément, pas découvrir un changement de comportement dans vos factures.

Étape 3 : La route de checkout

Une route POST /api/checkout lit l'offre demandée, résout le Price ID et crée une Checkout Session avec mode: "subscription", un client_reference_id pour votre utilisateur, et des success_url et cancel_url explicites. Renvoiez l'URL hébergée au navigateur. Ne fabriquez pas votre propre formulaire de paiement sans raison concrète.

Exigez un utilisateur connecté avant de créer la session. Le checkout invité ne laisse personne à qui accorder le droit : le webhook accorde l'accès par identifiant utilisateur ou e-mail de paiement, et si aucun ne correspond à un compte, la licence n'a pas de propriétaire. Lisez la session depuis les cookies dans le route handler, pas depuis un identifiant fourni par le client.

export async function POST(req: Request) {
  const user = await getSessionUser();           // côté serveur, depuis les cookies
  if (!user) return Response.json({ error: "unauthorized" }, { status: 401 });

  const { plan } = await req.json();
  const priceId = PLANS[plan]?.priceId;          // depuis l'env, jamais depuis le client
  if (!priceId) return Response.json({ error: "bad plan" }, { status: 400 });

  const session = await stripe.checkout.sessions.create({
    mode: "subscription",
    line_items: [{ price: priceId, quantity: 1 }],
    client_reference_id: user.id,
    customer_email: user.email,
    success_url: `${APP_URL}/billing?status=success`,
    cancel_url: `${APP_URL}/billing?status=cancel`,
  });

  return Response.json({ url: session.url });
}

Deux détails comptent. Le prix vient de votre environnement, jamais du corps de la requête — sinon un client peut choisir votre offre entreprise pour un dollar. Et les deux URL sont explicites ; compter sur les valeurs par défaut envoie les utilisateurs vers une page appartenant à Stripe après le paiement. L'ensemble des options de session est dans la référence API Checkout Sessions.

Un flux de session de checkout d'un utilisateur connecté vers une page de paiement hébergée par Stripe
Un flux de session de checkout d'un utilisateur connecté vers une page de paiement hébergée par Stripe

Étape 4 : Le webhook est la source de vérité

Le navigateur n'est pas fiable. Un client qui affirme « paiement réussi » ne prouve rien. Le webhook, signé par Stripe, est le signal faisant autorité. Vérifiez le corps brut contre l'en-tête Stripe-Signature avant d'analyser le JSON :

export async function POST(req: Request) {
  const sig = req.headers.get("stripe-signature");
  if (!sig) return new Response("missing signature", { status: 400 });

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(
      await req.text(),                  // octets bruts exacts
      sig,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch {
    return new Response("invalid signature", { status: 400 });
  }

  if (await alreadyProcessed(event.id)) return new Response(null, { status: 200 });
  await markProcessed(event.id);

  switch (event.type) {
    case "checkout.session.completed":
      await grantPlan(event.data.object.client_reference_id, "pro");
      break;
    case "customer.subscription.deleted":
      await revokePlan(event.data.object.metadata.userId);
      break;
  }
  return new Response(null, { status: 200 });
}

Analyser puis resérialiser modifie les octets et casse la vérification HMAC. Un échec de vérification — en-tête manquant, HMAC invalide, JSON malformé — doit lever une erreur et produire HTTP 400. Accuser réception d'une requête forgée avec 200 est un bogue de sécurité, pas une opération anodine. Le schéma de signature est expliqué dans la vérification de signature des webhooks, et le catalogue complet sous types d'événements webhook.

Un événement ignoré est différent d'un événement échoué. Un événement valablement signé que vous ne traitez pas doit être enregistré et reçoivre un 200 avec un drapeau « ignored ». N'utilisez jamais 200-ignored pour un échec de vérification.

Vérification du corps brut du webhook contre l'en-tête de signature avant l'analyse JSON
Vérification du corps brut du webhook contre l'en-tête de signature avant l'analyse JSON

Étape 5 : Rendre le webhook idempotent

Stripe réessaie les webhooks. Sans protection contre les rejeux, un paiement devient deux upgrades et une annulation devient un remboursement fantôme. Enregistrez les identifiants d'événements traités dans une table avec une contrainte d'unicité sur event_id, et insérez avant d'appliquer l'effet :

create table processed_events (
  event_id text primary key,
  received_at timestamptz not null default now()
);

L'insertion est le verrou : si un réessai concurrent utilise le même identifiant, la collision de clé primaire vous dit de passer. Faites vérification-et-marquage en une seule étape atomique plutôt qu'une lecture suivie d'une écriture, qui laisse une fenêtre de course. Attachez userId aux métadonnées de l'abonnement à la création de la session pour que l'événement d'annulation trouve le bon compte sans recherche par e-mail.

Un point à vérifier dans tout starter avant de vous engager : gère-t-il le webhook d'annulation ? Beaucoup de templates ne gèrent que checkout.session.completed et oublient customer.subscription.deleted, si bien que les clients gardent l'accès indéfiniment après annulation. Cherchez les deux types d'événements dans le code. S'il n'y en a qu'un, ajoutez l'autre avant le premier paiement.

Un journal d'idempotence qui applique chaque identifiant d'événement exactement une fois
Un journal d'idempotence qui applique chaque identifiant d'événement exactement une fois

Étape 6 : Le contrôle d'accès

Sur chaque route protégée ou server action, lisez l'offre dans la base de données — jamais depuis l'état client, ni depuis un cookie que vous auriez posé après le checkout. Si l'offre est inactive, renvoyez 402. Votre endpoint IA, le téléchargement du ZIP et les limites de sièges pendent tous de cette seule vérification :

export async function requirePro() {
  const user = await getSessionUser();
  if (!user) throw new HttpError(401);
  const { data } = await supabase
    .from("profiles")
    .select("plan")
    .eq("id", user.id)
    .single();
  if (data?.plan !== "pro") throw new HttpError(402, "Upgrade required");
}

Une vérification côté client qui cache un bouton est de l'UX, pas de la sécurité. C'est la vérification serveur qui compte. Si vous faites cela dans une Server Action plutôt qu'un route handler, la règle est la même ; la documentation des Server Actions montre comment garder la mutation côté serveur.

Un contrôle d'accès serveur renvoyant 402 pour une offre inactive
Un contrôle d'accès serveur renvoyant 402 pour une offre inactive

Étape 7 : Laisser les clients gérer et annuler

Un portail client supprime un ticket de support à chaque annulation. Créez une session Billing Portal côté serveur et redirigez l'utilisateur. Le portail gère la mise à jour de carte, le changement d'offre et l'annulation, et Stripe émet les webhooks correspondants, si bien que votre base reste synchronisée sans code supplémentaire. Le prorata des changements en cours de cycle y est aussi calculé pour vous — ne le recalculez pas vous-même à partir de timestamps.

Étape 8 : Tester la boucle entière

Utilisez le mode test et la carte 4242 4242 4242 4242 avec une date d'expiration future et un CVC arbitraire :

  1. Complétez le checkout ; confirmez que l'offre bascule dans la base.
  2. Annulez dans le portail ; confirmez qu'elle revient en arrière.
  3. Rejouez un événement checkout.session.completed capturé ; confirmez qu'il est appliqué une seule fois.
  4. Envoyez un webhook avec une signature corrompue ; confirmez 400, pas 200.
  5. Appelez un endpoint pro avec un utilisateur gratuit ; confirmez 402.

Pour la livraison locale, forwardez les événements avec la CLI Stripe (stripe listen --forward-to localhost:3000/api/webhooks) et copiez le secret de signature affiché dans STRIPE_WEBHOOK_SECRET. Tester contre une URL Preview déployée avec son propre endpoint et secret de webhook est plus propre si votre CI déploie déjà des Previews.

Si la boucle fonctionne avec un seul fichier d'environnement, votre facturation est réelle. Si une étape nécessite une modification manuelle de la base pour « finir », elle n'est pas finie.

Une boucle de test avec carte de test, rejeu, signature invalide et contrôle 402
Une boucle de test avec carte de test, rejeu, signature invalide et contrôle 402

Modes de défaillance courants

| Symptôme | Cause probable | Correction | | --- | --- | --- | | 400 sur chaque webhook | Mauvais secret de signature, ou corps analysé avant vérification | Utiliser le corps brut et le secret de l'endpoint correspondant | | L'offre ne bascule jamais | Événement traité mais client_reference_id vide | Exiger la connexion avant de créer la session | | L'offre bascule deux fois | Pas d'idempotence sur les identifiants d'événements | Table event_id unique, insertion atomique avant effet | | Checkout marche en local, pas en prod | Clé de test ou Price ID de test en production | Séparer les environnements, valider les clés au démarrage | | Le contrôle passe pour les gratuits | État client utilisé comme source de vérité | Lire l'offre dans la base à chaque requête |

Là où un boilerplate aide

Un bon boilerplate vous livre les étapes 3–6 déjà câblées et les garde derrière une interface indépendante du fournisseur. Cela compte dès que vous ajoutez Creem, PayPal, Waffo ou Lemon Squeezy pour une nouvelle région : vous écrivez un nouvel adaptateur au lieu de réécrire le checkout et les webhooks dans toute l'application. Uncorne ships five provider adapters behind one checkout and webhook contract, avec le chemin Stripe ci-dessus comme implémentation de référence.

Les règles de vérification ne changent pas avec le fournisseur. Vérifiez la signature sur les octets bruts, dédupliquez les identifiants d'événements, n'écrivez que depuis le serveur et gardez le contrôle d'accès côté serveur. Apprenez-les d'abord avec Stripe ; ils se transposent directement. Le raisonnement architectural plus profond est dans comment construire un SaaS avec Next.js.

Le résumé honnête

Les abonnements Stripe dans Next.js sont quatre pièces mobiles : un produit et un prix dans le tableau de bord, une route de checkout qui exige un utilisateur connecté, un webhook qui vérifie avant d'analyser et déduplique avant d'écrire, et un contrôle d'offre côté serveur. Faites ces quatre choses correctement et le chemin nominal devient presque ennuyeux — exactement ce que vous voulez d'un système de facturation. Tout le reste, de la tarification régionale à un second gateway, n'est qu'un adaptateur au-dessus de cette boucle.

FAQ

Faut-il analyser le corps du webhook avant de le vérifier ?+

Non. Vérifiez d'abord les octets bruts exacts contre l'en-tête Stripe-Signature, puis analysez. Analyser puis resérialiser modifie les octets et casse la vérification HMAC, qui doit renvoyer 400.

Pourquoi le checkout invité casse-t-il l'autorisation ?+

Le webhook accorde l'accès par identifiant utilisateur ou e-mail de paiement. Si personne n'est connecté et que l'e-mail ne correspond à aucun compte, la licence n'a pas de propriétaire. Exigez la connexion avant de créer la Checkout Session.

Que signifie une réponse webhook ignorée ?+

Un 200 avec un drapeau ignored signifie que l'événement était valablement signé mais n'est pas de ceux que vous traitez. Il ne doit jamais servir aux échecs de vérification, qui sont des 400. Enregistrez les événements ignorés pour les distinguer des échecs.

Comment empêcher un webhook réessayé d'upgrader deux fois un utilisateur ?+

Stockez les identifiants d'événements traités avec une contrainte d'unicité sur event_id et insérez l'identifiant de façon atomique avant d'appliquer l'effet. Si un réessai arrive, la collision de clé primaire vous dit de passer. Une lecture puis écriture laisse une fenêtre de course.

Faut-il utiliser Stripe Checkout ou l'élément de paiement intégré ?+

Commencez par Checkout hébergé : c'est le chemin le plus court vers les abonnements et Stripe héberge l'interface de paiement. Ne passez à l'élément intégré que si vous devez contrôler l'expérience de paiement dans votre propre page. La logique de webhook est identique dans les deux cas.

Toutes les questions fréquentes · Version Markdown (pour les agents IA)