# Flutter SDK integration

A guide to integrating the Peach Orchestration mobile SDK into a Flutter app using Dart and the `flutter_hyperswitch` package. Minimum: Flutter 3.0+, Dart 2.17+ (iOS 15.1, Android minSdk 21).

## What this page covers
- Ten sections: Prerequisites, Installation, Configuration, Basic integration, Payment methods, Saved cards, Error handling, Customisation, Testing, Troubleshooting
- Flutter/Dart prerequisites and getting Dashboard credentials (publishable key `pk_snd_xxx`/`pk_prd_xxx`)
- Adding the `flutter_hyperswitch` dependency and per-platform setup (Podfile, `build.gradle`)
- Initialising the SDK and presenting the payment sheet with a `client_secret` from your backend
- Payment methods, saved cards, and theming with `PaymentSheetAppearance`
- Handling the `presentPaymentSheet()` result map, testing and troubleshooting

## Key steps / API

Dependency in `pubspec.yaml`: `flutter_hyperswitch: ^version_number`, then `flutter pub get`.

```dart
import 'package:flutter_hyperswitch/flutter_hyperswitch.dart';

final _hyper = FlutterHyperswitch();

// 1. Initialise once at app startup
_hyper.init(HyperConfig(
  publishableKey: 'pk_test_your_publishable_key',
  customBackendUrl: 'https://app.sandbox-next.peachpayments.com/api',
));

// 2. Initialise the session with a client secret from your server
await _hyper.initPaymentSession(PaymentSheetParams(
  clientSecret: checkoutData.clientSecret,
));

// 3. Present the payment sheet (returns Map<String, dynamic>?)
final result = await _hyper.presentPaymentSheet();
```

Other real API surface referenced in the source:
- `FlutterHyperswitch()` — the SDK instance
- `HyperConfig(publishableKey, customBackendUrl)` — initialisation config
- `PaymentSheetParams(clientSecret: ...)` — session parameters
- `presentPaymentSheet()` returns a `Map<String, dynamic>?` result you inspect for status
- Theming: `PaymentSheetAppearance` with `PaymentSheetColors`, `PaymentSheetShapes`, `PaymentSheetTypography`, `PaymentSheetPrimaryButton`

Sandbox API base is `https://app.sandbox-next.peachpayments.com/api`; production is `https://app.next.peachpayments.com/api`. Always `await initPaymentSession` before calling `presentPaymentSheet`. If builds break, `flutter clean && flutter pub get`.

## Related
- [iOS SDK](/sdk-mobile-ios.md): the native iOS layer Flutter wraps
- [Android SDK](/sdk-mobile-android.md): the native Android layer Flutter wraps
- [Web SDK](/sdk-web.md): browser integration
- [API Playground](/playground.md): create a payment intent and get a `client_secret`
- [Testing](/docs/testing.md): test cards and sandbox guidance

---

Interactive version: https://playground.peachpayments.com/sdk-mobile/flutter