Configuration Stripe

Aperçu

Le template utilise Stripe Checkout pour les paiements et un registre de crédits pour accorder du solde après l’achat.

• UI : /[locale]/pricing lit les plans depuis un fichier TypeScript typé.
• Création de session : le client envoie POST /api/checkout puis est redirigé vers Stripe.
• Retour : Stripe renvoie l’utilisateur vers /api/pay/callback/stripe (GET).
• Finalisation serveur : Stripe envoie un webhook sur /api/pay/webhook/stripe (POST) qui marque la commande payée et crédite le compte.

Le webhook est la source de vérité ; le callback ne fait que rediriger.

Ressources de démarrage rapide

• Stripe : Bien démarrer — https://docs.stripe.com/get-started

Passerelles de paiement 101

Qu’est‑ce qu’une passerelle de paiement ?

Une passerelle de paiement est un service numérique qui permet aux entreprises en ligne de traiter et d’autoriser les paiements électroniques (cartes, portefeuilles numériques, virements). C’est l’équivalent en ligne d’un terminal de paiement. Elle sert d’intermédiaire et vérifie, approuve ou refuse les transactions de manière sécurisée.

Près de 7,4 billions de dollars de ventes e‑commerce sont attendus en 2025. Intégrer une passerelle est essentiel pour offrir une expérience de paiement fluide, améliorer la conversion et renforcer la sécurité et la confiance.

Comment fonctionnent les passerelles

1. Achat du client : saisie des informations de paiement sur votre checkout.
2. Chiffrement et envoi : le site chiffre et transmet les données à la passerelle.
3. Routage : la passerelle transfère les données chiffrées au processeur de paiement.
4. Communication avec l’émetteur : le processeur envoie les détails à la banque émettrice.
5. Approbation ou refus : décision en fonction des fonds et des contrôles de sécurité.
6. Réponse retour : la décision revient au processeur puis à la passerelle.
7. Finalisation : en cas d’approbation, confirmation côté client ; sinon, notification d’échec.
8. Règlement : les transactions approuvées sont réglées vers votre banque acquéreuse puis votre compte.

Malgré ces étapes, le processus est automatisé et ne prend que quelques secondes.

Intégrer une passerelle de paiement

1. Choisir un fournisseur : frais, moyens acceptés, sécurité, compatibilité plateforme.
2. Compte marchand : certains (ex. Stripe) l’incluent ; d’autres le nécessitent séparément.
3. Obtenir les clés API : authentifier votre site/app auprès de la passerelle.
4. Intégration : plugin (Shopify/WooCommerce) ou code. Les API Stripe sont très adaptées aux développeurs.
5. Tester en sandbox : valider les parcours avec des cartes de test.
6. Passer en production : utiliser les clés live et monitorer.

Endpoints

• /api/checkout (POST) : valide le plan (src/data/pricing.ts), crée la session, enregistre une order created.
• /api/pay/callback/stripe (GET) : redirection post‑Stripe ; ne finalise plus la commande.
• /api/pay/webhook/stripe (POST) : vérifie la signature et traite checkout.session.completed pour marquer paid et créditer.

Crédits

1. Récupération de order_no depuis les métadonnées de la session.
2. Mise à jour de la commande en paid + détails de paiement.
3. Ajout d’une ligne positive dans credits (order_pay).

Pré-requis

STRIPE_PRIVATE_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_WEB_URL=http://localhost:3000
NEXT_PUBLIC_PAY_CANCEL_URL=/pricing
NEXT_PUBLIC_PAY_SUCCESS_URL=/pricing
NEXT_PUBLIC_PAY_FAIL_URL=/pricing

Webhook local

stripe login
stripe listen --forward-to localhost:3000/api/pay/webhook/stripe
stripe trigger checkout_session_completed

Essayer

1. Créez un compte et connectez‑vous.
2. Ouvrez /[locale]/pricing et choisissez un plan.
3. Carte de test : 4242 4242 4242 4242.
4. Redirection vers le callback ; le webhook confirme et crédite.
5. Vérifiez /[locale]/credits-test ou POST /api/account/credits.

Guide d’intégration Stripe (aperçu)

Intégrer Stripe sur votre site est rapide si vous suivez ces étapes :

1. Créer un compte Stripe : renseigner votre activité et le compte de versement.
2. Récupérer les clés API : Dashboard → Developers (publishable & secret).
3. Installer les librairies : SDK Stripe officiel pour votre langage (JS/TS, Ruby, Python, etc.).
4. Frontend : utiliser Stripe.js et les composants (Elements/Payment Element) ou un plugin pour collecter les cartes en toute sécurité.
5. Backend : initialiser Stripe avec la clé secrète et exposer des endpoints pour PaymentIntents ou Checkout Sessions.
6. Collecter les données de paiement : éviter de manipuler les cartes côté serveur grâce aux composants Stripe.
7. Envoyer au serveur : transmettre l’intention de paiement en HTTPS.
8. Traiter côté serveur : créer PaymentIntents ou Checkout Sessions via le SDK.
9. Gérer la réponse : mettre à jour la base et informer le client.
10. Erreurs & cas limites : fonds insuffisants, carte expirée, 3DS, retries.
11. Tester à fond : mode test, webhooks et cartes de test.
12. Passer en live : basculer les clés, activer les méthodes et monitorer.

Astuce : démarrez avec le guide officiel — https://docs.stripe.com/get-started

Détails d’implémentation

• Plans : src/data/pricing.ts.
• handleCheckoutSession gère paiement unique et abonnement (PaymentIntent via latest_invoice).

Produits vs Prix (Stripe)

Stripe dissocie le catalogue (ce que vous vendez) de la tarification (comment c’est facturé) :

• Produit (prod_...) : nom/description, métadonnées catalogue ; un produit peut avoir plusieurs prix.
• Prix (price_...) : devise, montant, récurrence (mois/an), essais, comportement fiscal, paliers. Les abonnements s’attachent à un Prix.

Pourquoi référencer des IDs de Prix en Checkout

• Un abonnement nécessite des conditions tarifaires exactes. S’attacher à price_... permet les renouvellements corrects, le prorrata, les essais et Stripe Tax.
• Les renouvellements référencent le même price_... sur les lignes de facture, ce qui permet au webhook d’identifier le plan et d’accorder les crédits à chaque cycle.
• Plus sûr que des prix « ad‑hoc » : gérez montants/règles dans Stripe, le code reste stable.

Où trouver vos IDs de Prix dans Stripe

1. Dashboard → Produits → choisissez un produit.
2. Dans le tableau des Prix, cliquez sur les 3 points au bout de la ligne → « Copier l’ID du prix ».
3. Il commence par price_... — ne pas confondre avec l’ID produit (prod_...).

Variables d’environnement (optionnel mais recommandé)

# Faites correspondre vos plans aux Prix Stripe ; à défaut, fallback en price_data inline
NEXT_PUBLIC_STRIPE_PRICE_LAUNCH_MONTHLY=price_...
NEXT_PUBLIC_STRIPE_PRICE_SCALE_MONTHLY=price_...
NEXT_PUBLIC_STRIPE_PRICE_LAUNCH_YEARLY=price_...
NEXT_PUBLIC_STRIPE_PRICE_SCALE_YEARLY=price_...
# Variantes CNY (optionnel)
NEXT_PUBLIC_STRIPE_PRICE_LAUNCH_MONTHLY_CNY=price_...
NEXT_PUBLIC_STRIPE_PRICE_SCALE_MONTHLY_CNY=price_...
NEXT_PUBLIC_STRIPE_PRICE_LAUNCH_YEARLY_CNY=price_...
NEXT_PUBLIC_STRIPE_PRICE_SCALE_YEARLY_CNY=price_...

Comportement avec/sans IDs de Prix

• Si un plan d’abonnement possède un Price ID, Checkout l’utilise directement.
• Sinon, Checkout crée la session avec price_data inline depuis src/data/pricing.ts (repli sûr).

Renouvellements et Crédits

Les renouvellements sont gérés automatiquement :

• Webhook invoice.payment_succeeded (avec billing_reason=subscription_cycle) crée une commande de renouvellement et accorde les crédits du plan pour la période.
• Idempotence : on saute si une commande existe déjà pour (subscription_id, period_start).
• L’achat initial reste géré par checkout.session.completed ; pour éviter le double crédit, les factures hors cycle sont ignorées.

Facturation et Abonnements

Portail Client

Activez le Customer Portal de Stripe et choisissez ce que vos clients peuvent gérer (annuler/reprendre, mettre à jour la carte, consulter les factures).

Dans ce template :

• API : GET /api/billing/portal — crée une session du portail et redirige vers Stripe
• UI : /:locale/account/billing — bouton « Manage billing » qui ouvre le portail

Implémentation :

• Route API : src/app/api/billing/portal/route.ts
  • Recherche ou crée un Customer Stripe via l’email de l’utilisateur connecté
  • Crée une session de portail avec return_url vers /:locale/account/billing

Côté interface (Server Component) :

• src/app/[locale]/account/billing/page.tsx pointe vers /api/billing/portal?locale=<locale>

Relance (Paiements échoués)

Webhook : invoice.payment_failed déclenche un email demandant la mise à jour du moyen de paiement (via Resend).

• Template : src/services/email/templates/payment-failed.tsx
• Envoi : sendPaymentFailedEmail() dans src/services/email/send.ts
• Webhook : voir src/app/api/pay/webhook/stripe/route.ts

Test local avec Stripe CLI :

stripe trigger invoice_payment_failed

Remarque : l’email inclut un lien vers /:locale/account/billing pour ouvrir le portail depuis l’app.

Rappel : redirigez les webhooks en test

En local (ou toute URL hors production), assurez‑vous que Stripe redirige les événements vers votre backend ; sinon le paiement aboutit mais la commande/les crédits ne sont pas finalisés :

stripe listen --forward-to localhost:3000/api/pay/webhook/stripe

Si vous utilisez un domaine/tunnel distant, redirigez vers cette URL au lieu de localhost.

Autres options de paiement

Stripe n’est qu’une option. Si vous avez besoin d’alternatives comme les paiements en crypto ou PayPal, contactez‑moi : je peux vous aider à choisir et intégrer le bon fournisseur pour votre stack et votre marché.