StripeRECETTE MODE TEST
Prérequis
- Compte Stripe avec accès Developers → API keys (mode test activé)
- Variables d’environnement `.env.local` : `STRIPE_SECRET_KEY` et `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` préfixées `sk_test_` / `pk_test_`
- Checklist recette partagée PO + dev (Notion ou ClickUp)
- Stripe CLI installée ou tunnel webhook équivalent pour l’environnement local
Passer en production Stripe sans recette structurée expose le client à des paiements rejetés, des webhooks absents ou des montants incorrects. Le mode test simule cartes, authentification forte et remboursements sans mouvement bancaire réel. Vous allez séparer clés, données et scénarios avant la bascule live.
Séparer environnements test et live
Stripe isole totalement les objets test (PaymentIntent, Customer, Subscription) du mode live. Vos IDs `pi_test_…` ne existent pas en production.
Configurez Vercel Preview avec les clés test ; Production avec les clés live injectées au promote. Documentez la bascule dans le runbook client.
Le Dashboard Stripe bascule via le toggle « Test mode » : vérifiez l’indicateur avant toute manipulation manuelle (remboursement, resend webhook).
Checklist recette fonctionnelle
Scénario 1 — Paiement réussi : panier → Checkout → redirect succès → webhook reçu → commande « payée » en back-office.
Scénario 2 — Carte refusée : message utilisateur clair, commande reste « en attente », pas d’e-mail de confirmation.
Scénario 3 — 3-D Secure : modal authentification, puis succès ou échec selon le choix simulé.
Scénario 4 — Annulation : retour `cancel_url`, panier intact, aucune écriture stock.
Webhooks locaux avec Stripe CLI
Lancez `stripe listen --forward-to localhost:3000/api/webhooks/stripe`. Copiez le webhook signing secret affiché dans `.env.local` (`STRIPE_WEBHOOK_SECRET`).
Déclenchez un paiement test et confirmez la réception de `checkout.session.completed` dans les logs serveur.
Utilisez `stripe trigger payment_intent.succeeded` pour tester des handlers sans refaire un parcours UI complet.
Erreurs fréquentes
Clé publishable live côté front et secret test côté back : sessions invalides difficiles à diagnostiquer.
Recette uniquement en redirect sans tester le webhook : bug découvert en production le premier jour.
Oublier de basculer le webhook endpoint en live avec un nouveau secret signing.
Tester avec de vraies cartes en mode test : inutile et source de confusion.
Checklist recette non signée PO : régressions non détectées à la livraison.
Ce qu’il faut retenir
Mode test = clés `test_`, données isolées, cartes simulées documentées.
Quatre scénarios minimum : succès, refus, 3DS, annulation + webhook vérifié.
Stripe CLI accélère la recette webhook en local.
Bascule live = nouvelles clés, nouveaux secrets webhook, nouvelle checklist signée.
FAQ
Contrôlez le préfixe des clés dans les variables d’environnement et l’absence du badge « TEST DATA » dans Checkout hosté. Ajoutez un bandeau staging visible pour les préproductions client.
Oui, depuis le Dashboard ou l’API. Cela valide votre flux remboursement sans impact bancaire. Incluez un cas remboursement partiel dans la recette si le métier l’exige.
Oui. Les Price et Product test ne migrent pas automatiquement. Exportez un tableau de correspondance SKU → `price_live_…` avant la mise en production.
