arch-atlas

Stripe PaymentSheet

package:flutter_stripe · Stripe.instance

data

Overview

Direct integration with flutter_stripe's PaymentSheet. CheckoutController hands a clientSecret to initPaymentSheet and presentPaymentSheet handles every UI/UX detail (card entry, Apple Pay, 3DS).

User Flow

  1. Stripe.publishableKey is set once in main.dart from STRIPE_PUBLISHABLE_KEY (.env).
  2. createPaymentSession returns a clientSecret stored in CheckoutState.
  3. initPaymentSheet receives the clientSecret + merchantDisplayName.
  4. presentPaymentSheet awaits user interaction; success → continue, cancel → StripeException(Canceled).

Cases & Edge Cases

  • Style is fixed to ThemeMode.light — even when the app is in dark mode the sheet stays light (Stripe limitation we accepted).
  • Cancellation surfaces as a SnackBar, not a state.error — the user can simply retap Pay.
  • Re-presenting the sheet after a network error requires a fresh clientSecret — re-call createPaymentSession.

Code References

  • lib/main.dart // Stripe.publishableKey
  • lib/src/features/shared/checkout/controllers/checkout_controller.dart:360 // initPaymentSheet
  • lib/src/features/shared/checkout/controllers/checkout_controller.dart:371 // presentPaymentSheet

API Calls

Empty — fill this in later. Open the manifest and add content here.

Notes

flutter_stripe is imported with `hide Address` so its `Address` type doesn't collide with the local Address model — leave the import as-is. Native SDK contracts (no HTTP; embedded native plugin): • Stripe.instance.initPaymentSheet(SetupPaymentSheetParameters { paymentIntentClientSecret, merchantDisplayName, style: ThemeMode.light }) → void — screen: lib/src/features/shared/checkout/views/checkout_screen.dart • Stripe.instance.presentPaymentSheet() → success | StripeException(FailureCode.Canceled | …) — screen: lib/src/features/shared/checkout/views/checkout_screen.dart • Pre-step: read clientSecret from CheckoutState (populated by /store/payment-collections/{id}/payment-sessions response).