StripeCHECKOUT SESSION E-COMMERCE
Prérequis
- Compte Stripe avec clés test (publishable + secret) et webhook endpoint configuré
- Route API Next.js App Router pour créer la session côté serveur
- Catalogue produits avec prix en centimes et devise unique validée (ex. EUR)
- Checklist recette : scénarios succès, refus carte et annulation utilisateur
Un tunnel de paiement mal câblé génère des commandes fantômes, des paniers abandonnés sans trace ou des stocks décrémentés deux fois. Stripe Checkout centralise collecte carte, 3-D Secure et reçus dans une page hostée. Vous allez créer une Checkout Session côté serveur et valider le paiement par webhook, pas au redirect.
Cadrer le flux Checkout Session
Stripe Checkout propose une page hostée : line items, URLs de retour et options (livraison, codes promo). L’utilisateur paie sur stripe.com ; le statut arrive par webhook.
Parcours Next.js : panier → POST `/api/checkout` → session → redirection vers `session.url`. Le PO valide e-mail et adresse avant recette.
Mode `payment` pour achat ponctuel ; `subscription` pour les offres récurrentes (fiche abonnements SaaS).
Créer la session depuis Next.js
Installez `stripe` côté serveur. Construisez `line_items` depuis le panier validé (quantités, SKU, montants en centimes). Ne faites jamais confiance aux prix client sans recalcul serveur.
Renseignez `success_url` et `cancel_url` avec `?session_id={CHECKOUT_SESSION_ID}`. Activez `automatic_tax` seulement si Stripe Tax est configuré.
Retournez `{ url: session.url }` au front et redirigez l’utilisateur.
Webhooks et mise à jour commande
Configurez un endpoint webhook (ex. `/api/webhooks/stripe`) et vérifiez la signature `Stripe-Signature` avec le secret du endpoint.
Sur `checkout.session.completed`, récupérez `metadata.order_id`, vérifiez le montant et passez la commande au statut « payée ». Idempotence : ignorez les événements déjà traités (voir fiche webhooks Make).
Logguez `payment_intent`, `customer_email` et `amount_total` dans votre CMS ou base commandes pour le support client.
Erreurs fréquentes
Marquer la commande payée sur le seul redirect `success_url` : l’utilisateur peut fermer l’onglet avant le webhook.
Montants flottants au lieu de centimes entiers : Stripe rejette ou arrondit incorrectement.
Line items depuis le localStorage sans validation serveur : risque de fraude sur les prix.
Oublier `customer_email` ou `customer_creation` : relances et factures impossibles.
Ce qu’il faut retenir
Checkout Session = page hostée + line items + URLs retour, créée côté serveur.
La vérité métier du paiement arrive par webhook, pas par la page de succès.
Métadonnées `order_id` et validation des montants serveur sont non négociables.
Recette test : carte succès, refus, 3-D Secure et annulation avant mise en production.
FAQ
Checkout hosté accélère la mise en ligne et délègue PCI à Stripe. Payment Element convient si le tunnel reste 100 % dans votre UI. Pour un MVP e-commerce, Checkout hosté réduit la dette recette.
Utilisez les clés test et les numéros de carte documentés par Stripe (ex. 4242…). Vérifiez que votre webhook local écoute via Stripe CLI ou un tunnel sécurisé en développement.
Oui, activez `allow_promotion_codes` ou passez un `discount` / coupon pré-appliqué. Validez côté serveur que le coupon est encore actif avant de créer la session.
