Stripe intégration : guide complet pour développeurs Next.js
Tutoriel complet d'intégration Stripe + Next.js : Checkout, webhooks, abonnements et facturation.
Stripe est la plateforme de paiement en ligne la plus utilisee par les startups et les entreprises SaaS, traitant des milliards de dollars de transactions chaque annee. Son integration avec Next.js permet de creer des flux de paiement securises, des abonnements recurrents et des portails client en exploitant pleinement les API Routes et les Server Actions.
L'architecture de paiement Stripe repose sur un modele client-serveur strict : le front-end collecte les informations de paiement via Stripe.js (qui communique directement avec les serveurs Stripe sans jamais transiter par votre serveur), tandis que le backend gere la creation des sessions, la verification des webhooks et la logique metier. Ce modele garantit la conformite PCI DSS sans que vous ayez a manipuler des donnees de carte bancaire.
Ce guide detaille l'integration complete de Stripe dans un projet Next.js, depuis la configuration initiale jusqu'aux webhooks de production. Vous apprendrez a implementer Checkout Sessions, a gerer les abonnements avec le Customer Portal et a securiser les communications avec la verification des signatures de webhook.
1. Configuration initiale de Stripe avec Next.js
L'installation commence par npm install stripe @stripe/stripe-js @stripe/react-stripe-js. Le package stripe est la librairie serveur Node.js, @stripe/stripe-js charge Stripe.js cote client, et @stripe/react-stripe-js fournit les composants React (Elements, CardElement, PaymentElement). Les cles API se stockent dans .env.local : STRIPE_SECRET_KEY pour le serveur et NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY pour le client.
Cote serveur, on initialise le client Stripe avec new Stripe(process.env.STRIPE_SECRET_KEY, { apiVersion: '2024-12-18.acacia' }) dans un fichier utilitaire lib/stripe.ts. Specifier la version de l'API est crucial pour eviter les breaking changes inattendus. Cote client, loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY) retourne une Promise qui charge le script Stripe.js de maniere asynchrone.
Le mode test de Stripe utilise des cles prefixees par sk_test_ et pk_test_, permettant de simuler des transactions sans argent reel. Les numeros de carte de test (4242 4242 4242 4242 pour un paiement reussi, 4000 0000 0000 0002 pour un refus) couvrent tous les scenarios possibles. Le dashboard Stripe en mode test affiche les evenements et les logs en temps reel pour faciliter le debugging.
2. Checkout Sessions et flux de paiement
Stripe Checkout est une page de paiement hebergee par Stripe qui gere la collecte des informations de paiement, la validation 3D Secure et la conformite PCI. On cree une session via stripe.checkout.sessions.create() dans une Route API Next.js, en specifiant les line_items, le mode ('payment' pour un achat unique, 'subscription' pour un abonnement), et les URLs success_url et cancel_url de redirection.
Chaque line_item reference un Price ID cree dans le dashboard Stripe ou via l'API. Pour les prix dynamiques, le mode price_data permet de definir le montant a la volee avec unit_amount (en centimes), currency et product_data. L'option allow_promotion_codes active le champ de code promo directement dans l'interface Checkout, et shipping_address_collection collecte l'adresse de livraison.
Apres le paiement, la redirection vers success_url inclut un parametre session_id ({CHECKOUT_SESSION_ID}) que la page de confirmation utilise pour recuperer les details de la session via stripe.checkout.sessions.retrieve(). Il est essentiel de ne jamais se fier uniquement a cette page pour confirmer un paiement : les webhooks sont la seule source fiable pour declencher la logique metier (envoi d'email, activation de compte).
3. Webhooks et verification des signatures
Les webhooks Stripe envoient des evenements HTTP POST a votre endpoint a chaque changement d'etat : checkout.session.completed, invoice.paid, customer.subscription.updated, payment_intent.payment_failed. La Route API /api/webhooks/stripe recoit ces evenements et doit d'abord verifier la signature avant de traiter le payload. Sans cette verification, n'importe qui pourrait forger de faux evenements.
La verification de signature utilise stripe.webhooks.constructEvent(body, signature, webhookSecret) ou body est le corps brut de la requete (pas le JSON parse), signature est le header stripe-signature, et webhookSecret est la cle whsec_ configuree dans le dashboard. En Next.js App Router, il faut lire le body brut avec await request.text() au lieu de request.json() pour preserver la signature intacte.
En developpement local, la CLI Stripe (stripe listen --forward-to localhost:3000/api/webhooks/stripe) cree un tunnel qui redirige les evenements de test vers votre serveur local. La CLI affiche chaque evenement en temps reel et permet de les rejouer avec stripe events resend evt_xxx. En production, configurez la tolerance de retentative et les alertes email dans le dashboard pour etre notifie des echecs de livraison de webhooks.
Besoin d’aide en Technologie ?
Nos experts vous accompagnent. Recevez 3 devis gratuits sous 24h.
Gratuit · Sans engagement · Reponse sous 24h
4. Abonnements et Customer Portal
Les abonnements Stripe suivent le cycle : creation du Customer, attachement du PaymentMethod, creation de la Subscription avec le Price ID recurrent. L'evenement invoice.paid confirme chaque paiement mensuel ou annuel, tandis que customer.subscription.deleted signale une annulation. La prop trial_period_days ajoute une periode d'essai gratuite, et l'option proration_behavior gere les changements de plan en cours de cycle.
Le Customer Portal est une interface hebergee par Stripe ou les clients gerent eux-memes leurs abonnements : changement de plan, mise a jour de la carte bancaire, telechargement des factures et annulation. On cree une session portail via stripe.billingPortal.sessions.create({ customer: customerId, return_url: 'https://app.com/account' }). La configuration du portail (plans visibles, options d'annulation) se definit dans le dashboard Stripe.
Pour synchroniser l'etat de l'abonnement avec votre base de donnees, ecoutez les webhooks customer.subscription.created, updated et deleted. Stockez le subscription_id, le status (active, past_due, canceled) et la current_period_end dans votre table users. Un middleware Next.js verifie ce statut a chaque requete pour restreindre l'acces aux fonctionnalites premium aux abonnes actifs.
5. Securite et bonnes pratiques en production
La regle de securite fondamentale avec Stripe est de ne jamais manipuler de donnees de carte bancaire cote serveur. Utilisez exclusivement Stripe Checkout ou les Payment Elements qui tokenisent les informations directement vers les serveurs Stripe. Votre serveur ne recoit qu'un token ou un PaymentMethod ID, garantissant la conformite PCI DSS SAQ A sans questionnaire complexe.
L'idempotence est essentielle pour eviter les doubles paiements : chaque appel API Stripe accepte un header Idempotency-Key qui garantit qu'une requete identique n'est executee qu'une seule fois. En cas de timeout ou d'erreur reseau, le client peut renvoyer la meme requete en toute securite. Generez une cle unique par operation metier (par exemple l'ID de commande) plutot qu'un UUID aleatoire.
La gestion d'erreurs Stripe distingue trois categories : les erreurs de carte (card_error) a communiquer a l'utilisateur, les erreurs de requete (invalid_request_error) indiquant un bug dans votre code, et les erreurs API (api_error) signalant un probleme temporaire cote Stripe. Un try-catch structure autour de chaque appel API avec un switch sur err.type permet de traiter chaque cas de maniere appropriee et de fournir des messages d'erreur clairs.
Questions frequentes
Stripe Checkout ou Payment Elements : lequel choisir ?
Stripe Checkout est une page hebergee par Stripe, ideale pour les flux simples sans personnalisation poussee. Payment Elements sont des composants integres dans votre propre page, offrant un controle total sur le design. Checkout reduit le temps d'integration a quelques heures, tandis que Payment Elements peut necessiter plusieurs jours mais offre une experience sur-mesure.
Comment tester les webhooks en local avec Next.js ?
Installez la CLI Stripe (brew install stripe/stripe-cli/stripe), authentifiez-vous avec stripe login, puis lancez stripe listen --forward-to localhost:3000/api/webhooks/stripe. La CLI affiche un webhook signing secret temporaire a utiliser dans votre .env.local. Declenchez des evenements de test avec stripe trigger checkout.session.completed.
Comment gerer les echecs de paiement recurrents ?
Stripe Smart Retries tente automatiquement les paiements echoues selon un calendrier optimise par machine learning. Configurez les emails de relance automatiques dans le dashboard (Settings > Subscriptions > Manage failed payments). Ecoutez l'evenement invoice.payment_failed pour notifier l'utilisateur dans votre application et afficher un bandeau de mise a jour de carte.
Les prix doivent-ils etre crees dans le dashboard ou via l'API ?
Pour les produits avec des prix fixes (plans SaaS), creez-les dans le dashboard et referencez les Price IDs dans votre code. Pour les prix dynamiques (devis personnalises, tarification au volume), utilisez price_data dans la session Checkout. Ne codez jamais les montants en dur dans le front-end, car ils peuvent etre manipules par l'utilisateur.
Comment facturer en euros et gerer la TVA avec Stripe ?
Specifiez currency: 'eur' dans vos Price objects et activez Stripe Tax pour le calcul automatique de la TVA selon la localisation du client. Stripe Tax gere les taux de TVA pour l'UE, la Suisse et le Royaume-Uni. Pour les entreprises assujetties a la TVA, le champ tax_id_collection dans Checkout collecte et verifie automatiquement les numeros de TVA intracommunautaire.
Guides complementaires
Next.js 14 : guide complet du App Router en français
Guide complet du App Router Next.js 14 en français : layouts, server components, data fetching et déploiement.
TechnologieTailwind CSS : guide complet et bonnes pratiques 2025
Guide complet Tailwind CSS : configuration, responsive design, dark mode, composants réutilisables et bonnes pratiques.
TechnologieAPI REST vs GraphQL : quel choix pour votre projet
Comparatif détaillé REST vs GraphQL : performances, flexibilité, sécurité et cas d'usage pour choisir votre API.
Outils gratuits recommandes
Lancez votre projet technologie
500+ experts verifies prets a vous accompagner. Devis gratuit sous 24h.