feat(#458): S7 Stripe payment + latching surge + saved card branch

[alexpmichelet]

Closes #458

Summary

Wires the PWA /checkout Stripe payment flow on top of the merged backend (2.5-B paymentIntent + 2.5-D savedCard + 2.6-B latching). Bridges the gap between S6 (push-enrollment gate) and /c/[orderId] (tracking).

At click-Payer the form runs

1. recordCheckoutContact — capture PII for next visit's prefill (NEW mutation, closes the loop the S6 decide-prefill.ts comment flagged as « S7 scope »).
2. recordConsentAtCheckout — stamp CGV hash (ADR 0007).
3. recaptureQuoteAtPayment → decideLatchingOutcome :
   • abort → toast with the verdict's reason (hors_horaire / surge / hors_zone)
   • confirm-surge → blocking <LatchingConfirmModal> (Esc / click-outside prevented)
   • ok → continue with the FRESH fee
4. createOrderFromCart → orderId
5. Branch on decidePaymentBranch(fiche) :
   • saved-card → payWithSavedCard (clone + direct charge) → redirect /c/[orderId]
   • new-card → createPaymentIntent → stripe.confirmPayment({elements, clientSecret, confirmParams: {return_url}}) (3DS / Apple Pay handled by SDK)
6. On failure → decideRetryAction(attempts) :
   • ≤2 attempts → inline retry banner
   • ≥3 attempts → fatal toast + captureException (Sentry shim)

Lazy load (acceptance criterion satisfied)

The Stripe SDK is loaded via next/dynamic({ ssr: false }) (<StripePaymentLazy>), keeping @stripe/* out of every bundle except /checkout. The S6 gate-disabled branch (modal only) also never loads the SDK.

Architecture

Layer	File	Role
Pure decisions	apps/web/src/lib/stripe-payment/	decidePaymentBranch / decideLatchingOutcome / decideRetryAction / derivePricingSnapshot + captureException shim
Lazy boundary	stripe-payment/stripe-payment-lazy.tsx	next/dynamic import
Stripe provider	stripe-payment/stripe-elements-provider.tsx	loadStripe(pk, { stripeAccount }) + deferred-intent <Elements>
Branches	saved-card-panel.tsx, new-card-panel.tsx (<PaymentElement>)	Per-branch UI
Orchestrator	stripe-payment-section.tsx	The 6-step click-Payer flow above
Backend	lib/customer/checkoutContact.ts	NEW recordCheckoutContact mutation (self-scoped, cross-tenant fuzz, sanctioned seam patchCustomerCheckoutContact)
Backend	lib/tenants/payment.ts	NEW forCheckout customer-scoped query → {stripeAccountId, stripeStatus} for Elements init

Known scope gap (documented)

The « Sauvegarder ma carte » checkbox mentioned in the issue description is deliberately NOT rendered V1 — cross-resto save (which is the whole value of the saved-card UX) requires a platform-level SetupIntent flow the existing backend saveCard action expects but V1 doesn't yet collect. The CONSUMPTION side (saved-card tile pre-selected) is fully wired through <SavedCardPanel> + payWithSavedCard. Detailed rationale in new-card-panel.tsx header. Follow-up slice: add createPlatformSetupIntent + a second platform-context Elements instance branching the new-card flow on the « save » intent.

Guardrails (project rules)

• All new mutations/queries via sanctioned wrappers (customerMutation / customerQuery) — no raw ctx.db in business code.
• No getAuthUserId — identity flows through getCurrentActor (ADR 0011).
• Cross-tenant fuzz on every new tenant-scoped surface (checkoutContact, tenants.payment.forCheckout).
• All sensitive ctx.db.patch sites for customers extended through patchCustomerCheckoutContact (sanctioned seam in lib/tenancy/customerFiche.ts).
• No secrets / no template structure changes / crypto stays in Node routes.

Plan de test E2E

Scénario 1 — Paiement saved card cross-resto (US 45)

• Acteur : Sophie sur iPhone Safari, cookie session valide, fiche customer avec savedPaymentMethodId non-null (peut être seedé manuellement via saveCard action, OR avoir payé sur un autre resto KB)
• Pré-requis :
  • Tenant test-t1 avec stripeAccountId + stripeStatus: ready
  • Customer fiche avec savedPaymentMethodId: pm_test_visa_4242 + stripeCustomerId: cus_test_… (Stripe Dashboard sandbox)
  • Push enrollment active (Wallet OU webPush OU noChannelPossible=true) — sinon Payer ouvre la modal push
  • Cart avec ≥1 item, address-first validé
• URL de départ : https://test-t1.kitchen-boost.fr/checkout
• Étapes :
  1. Vérifier que le tile « Payer avec ma carte enregistrée » apparaît pré-sélectionné (et qu'il y a un lien « Utiliser une autre carte »)
  2. Taper « Payer XX € »
  3. Observer le redirect automatique vers /c/<orderId>
• Attendu :
  • Tile saved card visible avant clic
  • Aucun formulaire carte Stripe affiché
  • Après clic : /c/[orderId] rendu (page tracking)
  • Stripe Dashboard sandbox montre la commande payée + 240 cts application_fee
• Couvre : US 45 (saved card), US 50 (redirect tracking), slice S7 — Stripe payment + latching surge + Apple Pay verification #458

Scénario 2 — Paiement nouvelle carte avec 3DS (US 46 + US 49)

• Acteur : Sophie sur iPhone Safari, fiche SANS saved card
• Pré-requis : idem scénario 1 mais savedPaymentMethodId: undefined
• URL de départ : https://test-t1.kitchen-boost.fr/checkout
• Étapes :
  1. Vérifier que le Payment Element Stripe s'affiche avec le bouton Apple Pay visible (haut de la modal Stripe)
  2. Saisir la carte test 3DS Stripe 4000 0027 6000 3184, expiration 12/34, CVC 123
  3. Taper « Payer XX € »
  4. Sur la sheet 3DS qui s'ouvre, taper « Complete authentication »
  5. Observer le redirect automatique vers /c/<orderId>
• Attendu :
  • Payment Element rendu correctement (cf. DevTools Network : m.stripe.com requests apparaissent UNIQUEMENT au mount de /checkout, JAMAIS sur /menu)
  • Apple Pay button rendu en haut iOS
  • Sheet 3DS Stripe ouverte sans code custom
  • Post-3DS : redirect natif vers /c/<orderId>
  • Stripe Dashboard : payment_intent.succeeded webhook reçu
• Couvre : US 46 (Payment Element + Apple Pay), US 49 (3DS auto), AC « 3DS handle par SDK sans code custom », AC « Bundle Stripe lazy-loaded »

Scénario 3 — Latching anti-surge (US 47)

• Acteur : Sophie sur Android Chrome
• Pré-requis :
  • Address validée → verdict cached avec fee=350 cts
  • Patch backend manuel : forcer recaptureQuoteAtPayment à retourner {deliverable: true, fee: 590, eta: 1700, quoteId: 'qt_surge'} (e.g. mock lib/uberDirect/quote.requestQuote à retourner 590 cts pour la durée du test, OU patch directement le row Uber côté test).
• URL de départ : https://test-t1.kitchen-boost.fr/checkout
• Étapes :
  1. Taper « Payer XX € »
  2. Observer la modal <LatchingConfirmModal> qui s'ouvre avec « Le tarif livraison est passé de 3,50 € à 5,90 € »
  3. Vérifier qu'Esc et clic en dehors NE FERMENT PAS la modal
  4. Taper « Oui, payer 5,90 € de livraison »
  5. Observer que le flow continue (Payment Element ou redirect saved-card)
• Attendu :
  • Modal bloquante affichée
  • Esc / click-outside ne ferment pas
  • Sur « Oui » → flow paiement reprend avec FRESH fee dans le pricingSnapshot
  • Sur « Non » → retour à idle, AUCUNE commande créée
• Couvre : US 47 (latching surge), AC « Latching : surge artificiel → modal confirm bloquant apparaît »

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
kitchen-boost-repo-admin	Ready	Preview, Comment	Jun 10, 2026 7:52pm
kitchen-boost-repo-web	Ready	Preview, Comment	Jun 10, 2026 7:52pm