peachpayments_flutter 1.1.0

Peach Payments SDK for Flutter — accept card and alternative payments in your Flutter app with a prebuilt, customisable payment sheet.

peachpayments_flutter

Peach Payments SDK for Flutter — accept card and alternative payments in your Flutter app with a prebuilt, customisable payment sheet.

Wraps Peach Payments' native Android and iOS SDKs behind a single Dart API.

---

⚠️ Setup is not just flutter pub add

Peach Payments' native artefacts are not published to Maven Central or the CocoaPods trunk. You must configure two extra things or your first build will fail:

Platform	What you need
Android	A GitLab deploy token (PEACH_MAVEN_TOKEN) for the Peach Maven registry
iOS	The Peach CocoaPods spec repo added as a source in your Podfile

Both are covered in Installation below. Ask your Peach Payments contact for a deploy token if you do not have one.

Installation

1. Add the dependency

dependencies:
  peachpayments_flutter: ^1.0.0

Optional feature packages — add only what you need, each links an extra native dependency:

  peachpayments_flutter_netcetera_3ds: ^1.0.0  # Netcetera 3-D Secure
  peachpayments_flutter_scancard: ^1.0.0       # card scanning

Then flutter pub get.

2. Android

Run the helper once. It writes the Gradle plugin and the required Maven repositories into your app's Gradle files:

dart run peachpayments_flutter:apply_plugins

This is a manual step — pub has no post-get hook, so it cannot run automatically. It is safe to re-run: the script is idempotent and will also upgrade an older Gradle plugin version in place.

Then supply your deploy token as a Gradle property or environment variable:

PEACH_MAVEN_TOKEN=<your deploy token>

Keep the token out of version control — put it in ~/.gradle/gradle.properties or inject it from CI secrets, not in the app's android/gradle.properties.

The registry URL defaults to the Peach Maven registry (https://gitlab.com/api/v4/projects/81506485/packages/maven); set PEACH_MAVEN_URL only if you need to point at a different project.

If your app routes dependency resolution through settings.gradle (dependencyResolutionManagement with FAIL_ON_PROJECT_REPOS or PREFER_SETTINGS), Gradle ignores the repositories in android/build.gradle — apply_plugins will warn and print the block to add there instead.

The SDK requires minSdk = 24; apply_plugins sets this for you.

3. iOS

Add the Peach spec repo to the top of ios/Podfile. A podspec cannot declare its own sources, so every consuming app needs these two lines:

source 'https://github.com/peach-payments/hyperswitch-sdk-ios.git'
source 'https://cdn.cocoapods.org/'

platform :ios, '15.1'

Then cd ios && pod install. Minimum deployment target is iOS 15.1.

Usage

import 'package:peachpayments_flutter/peachpayments_flutter.dart';

final _peach = PeachPayments();

// 1. Configure the SDK with your publishable key.
_peach.init(PeachPaymentsConfig(publishableKey: publishableKey));

// 2. Open a session against a client secret from your backend.
final session = await _peach.initPaymentSession(
  PaymentMethodParams(
    clientSecret: clientSecret,
    configuration: Configuration(
      merchantDisplayName: 'My Store',
      primaryButtonLabel: 'Pay',
    ),
  ),
);

// 3. Present the payment sheet.
final result = await _peach.presentPaymentSheet(session);

switch (result.status) {
  case Status.completed:
    // payment succeeded
    break;
  case Status.cancelled:
    // customer dismissed the sheet
    break;
  case Status.failed:
    debugPrint(result.error.message);
    break;
}

Errors are surfaced as PeachPaymentsException:

try {
  final session = await _peach.initPaymentSession(params);
} on PeachPaymentsException catch (e) {
  debugPrint('${e.code}: ${e.message}');
}

Saved payment methods (headless)

To charge a returning customer without showing the sheet:

final saved = await _peach.getCustomerSavedPaymentMethods(session);

// Inspect the default or last-used method before charging.
final method = await _peach.getCustomerLastUsedPaymentMethodData(saved);
if (method is PaymentMethod) {
  final result = await _peach.confirmWithLastUsedPaymentMethod(saved);
}

iOS limitation on confirmWithLastUsedPaymentMethod. If the saved card requires a CVC (requiresCvv), iOS cannot confirm it headlessly — the SDK needs a CVCWidget the customer types into. The call fails with a clear message; use presentPaymentSheet for those cards. Android accepts a null CVC and has no such restriction.

Available calls:

Method	Returns
init(PeachPaymentsConfig)	—
initPaymentSession(PaymentMethodParams)	Session
presentPaymentSheet(Session)	PaymentResult
getCustomerSavedPaymentMethods(Session)	SavedSession
getCustomerDefaultSavedPaymentMethodData(SavedSession)	PaymentMethodResponse
confirmWithCustomerDefaultPaymentMethod(SavedSession)	PaymentResult
getCustomerLastUsedPaymentMethodData(SavedSession)	PaymentMethodResponse
confirmWithLastUsedPaymentMethod(SavedSession)	PaymentResult

Customising the sheet

Configuration.appearance accepts an Appearance object covering layout, colours, fonts, and the Google Pay / Apple Pay button styles:

Configuration(
  appearance: Appearance(
    layout: Layout.spacedAccordion,
    font: Font(family: 'Montserrat'),
    colors: DynamicColors(
      light: ColorsObject(primary: '#8DBD00', background: '#F5F8F9'),
      dark: ColorsObject(primary: '#8DBD00', background: '#F5F8F9'),
    ),
    primaryButton: PrimaryButton(shapes: Shapes(borderRadius: 32.0)),
  ),
)

Custom fonts must also be declared in your app's pubspec.yaml fonts: section — the native side loads them by family name from your Flutter assets.

Example

See apps/example for a complete app, including a sample backend for creating payment intents.

Migrating from flutter_hyperswitch

This package replaces the upstream flutter_hyperswitch package. The public API is the same shape; the names changed:

Before	After
package:flutter_hyperswitch/flutter_hyperswitch.dart	package:peachpayments_flutter/peachpayments_flutter.dart
FlutterHyperswitch	PeachPayments
HyperConfig	PeachPaymentsConfig
HyperParams	PeachPaymentsParams
HyperswitchException	PeachPaymentsException
FlutterHyperswitchPlatform	PeachPaymentsPlatform
MethodChannelFlutterHyperswitch	MethodChannelPeachPayments

Method names and payment-domain types (Session, PaymentResult, Configuration, Appearance, …) are unchanged. The native dependencies now resolve to Peach Payments' io.peachpayments Android artefacts and peachpayments-hyperswitch-ios pods, which is why the extra repository setup above is required.

Licence

Apache-2.0 — see LICENSE and NOTICE. Derived from Juspay's Hyperswitch client SDK.