Flutter SDK

Integrate Plexy with Flutter mobile applications

The official Plexy SDK for Flutter. Build a full checkout with Drop-in, or compose individual payment Components. Works on both iOS and Android, with the Sessions flow (recommended) or the Advanced flow.

Requirements

Flutter 3.16 or later

Dart 3.2 or later

iOS 12 or later

Android API level 21 (Android 5.0) or later

Plexy Checkout API v2 or later

Installation

Copy install command: flutter pub add plexy_checkout

Add the package to your app:

Or add it manually to pubspec.yaml:

Then run flutter pub get.

Platform Setup

Android

Set minSdkVersion to 21 in android/app/build.gradle:

Make sure your project uses Kotlin 1.8.22 or later and Android Gradle Plugin 8.1 or later.

Change your MainActivity to extend FlutterFragmentActivity — the native Plexy Android SDK requires it:

iOS

Set the iOS deployment target to 12.0 or later in ios/Podfile:

Add a custom URL scheme for your return URL in ios/Runner/Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>com.yourcompany.yourapp</string>
    </array>
  </dict>
</array>

Forward the return URL to the SDK in ios/Runner/AppDelegate.swift:

If you handle other URL schemes in the same AppDelegate, combine the results (e.g. return handledByOther || true) instead of falling through to super, which returns false.

Get the matching return URL at runtime with await PlexyCheckout.instance.getReturnUrl(). Pass this value to your backend when creating a session or payment.

Quick Start: Drop-in with Sessions Flow

The Sessions flow is the simplest way to accept payments. Your backend creates a session, your app renders Drop-in.

1. Create a session on your backend. Call POST /sessions on the Plexy Checkout API with the amount, country, and return URL, and return id and sessionData to your app.

2. Open Drop-in:

See Handling the payment result for handleResult.

Drop-in with Advanced Flow

Use the Advanced flow when you need to control each /payments and /payments/details call yourself.

onSubmit and onAdditionalDetails both return a PaymentEvent:

Finished(resultCode) — terminal; Drop-in closes.

Action(actionResponse) — Drop-in runs the additional action (3DS, redirect, QR).

Update(paymentMethodsJson, orderJson) — refresh Drop-in (used for gift cards / partial payments).

Error(errorMessage, reason, dismissDropIn) — show an error.

Configuring Drop-in

DropInConfiguration accepts per-method configs:

Also available on DropInConfiguration: cashAppPayConfiguration, storedPaymentMethodConfiguration (showing and deleting saved methods), and skipListWhenSinglePaymentMethod. See the plugin source for the full field list of each configuration.

Card Component

Render the Card Component as a Flutter widget inside your own screen. It works with either SessionCheckout or AdvancedCheckout.

For the Advanced flow, construct an AdvancedCheckout (as shown above) and pass it as checkout. Fetch the list of payment methods from POST /paymentMethods and extract the scheme entry the same way.

Apple Pay Component

Requires the Apple Pay entitlement (Merchant IDs capability) on your iOS app.

Google Pay Component

Google Pay requires Play Services Wallet, which is bundled by the plugin — no extra Gradle changes needed.

Handling the Payment Result

PaymentResult is a sealed class. Switch on it:

ResultCode values: authorised, refused, pending, cancelled, error, received, redirectShopper, identifyShopper, challengeShopper, presentToShopper, partiallyAuthorised, authenticationFinished, authenticationNotRequired, unknown.

Never treat the client-side resultCode as a source of truth for "payment completed" — always confirm on the server via webhooks or a GET /sessions/{id} poll.

Return URL

Pass the value returned by PlexyCheckout.instance.getReturnUrl() into the returnUrl field of your POST /sessions or POST /payments request. On iOS this value matches the URL scheme you registered in Info.plist; on Android the plugin uses an auto-generated scheme.

Debugging

Enable plugin console logging in debug builds:

The call is a no-op in release builds.

Plexy SDK for Flutter

Flutter SDK#

Installation#

Platform Setup#

Android#

iOS#

Quick Start: Drop-in with Sessions Flow#

Drop-in with Advanced Flow#

Configuring Drop-in#

Card Component#

Apple Pay Component#

Google Pay Component#

Handling the Payment Result#

Return URL#

Debugging#

Flutter SDK

Installation

Platform Setup

Android

iOS

Quick Start: Drop-in with Sessions Flow

Drop-in with Advanced Flow

Configuring Drop-in

Card Component

Apple Pay Component

Google Pay Component

Handling the Payment Result

Return URL

Debugging