peachpayments_flutter 1.2.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. Each platform needs one extra repository declared, or your first build will fail:

Platform	What you need
Android	The Peach Maven registry. No credentials required — it allows anonymous reads, and apply_plugins writes it in for you
iOS	The Peach CocoaPods spec repo added as a source in your Podfile

Both are covered in Installation below.

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.

That is all that is needed. The registry (https://gitlab.com/api/v4/projects/81506485/packages/maven) allows anonymous reads, so no token or credentials are required.

Two optional overrides exist for unusual setups:

Property	When you need it
PEACH_MAVEN_URL	Point at a different project's registry
PEACH_MAVEN_TOKEN	Only if that registry requires authentication

If you do use a token, keep it out of version control — put it in ~/.gradle/gradle.properties or inject it from CI secrets, not the app's android/gradle.properties.

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.

Payment method logos

The package bundles SVG logos for the payment methods Peach supports, so you can build your own method pickers or summaries without shipping the artwork yourself:

PeachPaymentMethodLogo(PeachPaymentMethod.capitecPay, height: 24)

// Or straight from an API key such as `pay_shap`; unknown keys render `fallback`.
PeachPaymentMethodLogo.fromKey('pay_shap', height: 24, fallback: Icon(Icons.payment))

// Apple Pay has a white variant for dark backgrounds.
PeachPaymentMethodLogo(PeachPaymentMethod.applePay, height: 24, onDark: true)

PeachPaymentMethod.logoAssetPath() returns the raw asset path if you want to load it with SvgPicture.asset(path, package: 'peachpayments_flutter') yourself. Logos are available for: capitec_pay, pay_shap, peach_eft, payflex, zero_pay, float, happy_pay, mobicred, a_plus, rcs, payjustnow, apple_pay, scan_to_pay, one_for_you, google_pay, money_badger, blink_by_emtel, maucas, mcb_juice, mpesa.

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.