checkout_com_flow

A Flutter plugin that integrates Checkout.com Flow payment components for Android and iOS.

Flow provides a pre-built, customizable payment UI that handles card payments, Apple Pay, Google Pay, and other payment methods — all managed by Checkout.com.

DISCLAIMER — UNOFFICIAL PLUGIN

This package is NOT an official Checkout.com product. It is an independent, community-driven project and is not affiliated with, endorsed by, sponsored by, or in any way officially connected to Checkout.com or any of its subsidiaries or affiliates.

The official Checkout.com website can be found at https://www.checkout.com.

For any questions, issues, or support regarding Checkout.com products and services, please contact Checkout.com directly:

The names "Checkout.com", "Flow", and any related trademarks are the property of their respective owners.

Warranty & Liability

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.

IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The authors of this plugin:

  • Make no guarantees about the correctness, reliability, or security of this software.
  • Accept no responsibility for any financial loss, data breach, or other damages resulting from the use of this plugin.
  • Provide no warranty that this plugin will be compatible with current or future versions of the Checkout.com APIs or SDKs.
  • Offer no official support — issues may be filed on the repository, but responses are on a best-effort basis.

By using this plugin, you acknowledge that you do so entirely at your own risk.

For production payment processing, always refer to the official Checkout.com documentation and consider using the official native SDKs directly.

Features

  • Native Checkout.com Flow UI embedded as a Flutter widget
  • Supports Android (Jetpack Views) and iOS (SwiftUI via UIKit bridge)
  • Sandbox and Production environments
  • Typed result callbacks (success, error, cancelled)
  • Apple Pay and Google Pay support (managed by Flow)
  • Full theme customization — colors, border radius, dark mode support
  • Component type selection — full Flow or card-only mode
  • iOS uses Swift Package Manager for the native Checkout.com SDK dependency

Requirements

Platform Minimum Version
Android API 21 (5.0)
iOS 15.0
Flutter 3.10.0
Dart 3.0.0

API Key Scopes

Your Checkout.com public key must have these scopes enabled:

  • payment-sessions:pay
  • vault-tokenization

Your secret key (server-side only) must have:

  • payment-sessions

Installation

Add to your pubspec.yaml:

dependencies:
  checkout_com_flow: ^1.1.0

Then run:

flutter pub get

Android Setup

Ensure mavenCentral() is in your project-level build.gradle repositories:

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

iOS Setup

The plugin uses Swift Package Manager to resolve the Checkout.com native SDK. No additional setup is needed if your project uses CocoaPods — the vendored xcframework is included.

If you encounter build issues on Xcode 16+, ensure the podspec includes SWIFT_ENABLE_EXPLICIT_MODULES => NO (already set in the published version).

Usage

1. Create a Payment Session (server-side)

Call the Checkout.com Payment Sessions API from your backend:

curl -X POST https://api.checkout.com/payment-sessions \
  -H "Authorization: Bearer sk_sbox_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "GBP",
    "reference": "ORD-123",
    "display_name": "My Shop",
    "billing": { "address": { "country": "GB" } },
    "customer": { "name": "Jane Doe", "email": "jane@example.com" },
    "success_url": "https://example.com/success",
    "failure_url": "https://example.com/failure"
  }'

The response contains id, paymentSessionToken, and paymentSessionSecret.

2. Render the Flow widget

import 'package:checkout_com_flow/checkout_com_flow.dart';

CheckoutFlowWidget(
  config: CheckoutFlowConfig(
    publicKey: 'pk_sbox_xxx',
    paymentSessionId: 'ps_xxx',
    paymentSessionSecret: 'secret_xxx',
    environment: CheckoutFlowEnvironment.sandbox,
  ),
  onResult: (result) {
    switch (result) {
      case CheckoutFlowSuccess(:final paymentId):
        print('Payment successful: $paymentId');
      case CheckoutFlowError(:final message):
        print('Payment error: $message');
      case CheckoutFlowCancelled():
        print('Payment cancelled');
    }
  },
  onReady: () {
    print('Flow component is ready');
  },
  height: 420,
)

3. Dark mode theme

Use the built-in dark theme preset or customize individual colors:

CheckoutFlowWidget(
  config: CheckoutFlowConfig(
    publicKey: 'pk_sbox_xxx',
    paymentSessionId: 'ps_xxx',
    paymentSessionSecret: 'secret_xxx',
    // Use the dark theme preset
    theme: const CheckoutFlowTheme.dark(),
  ),
  onResult: _handleResult,
)

4. Custom theme

Customize every color and border radius:

CheckoutFlowWidget(
  config: CheckoutFlowConfig(
    publicKey: 'pk_sbox_xxx',
    paymentSessionId: 'ps_xxx',
    paymentSessionSecret: 'secret_xxx',
    theme: const CheckoutFlowTheme(
      actionColor: '#FF6B00',       // Pay button color
      backgroundColor: '#1A1A2E',   // Container background
      formBackgroundColor: '#2A2A3E', // Input fields background
      formBorderColor: '#4A4A5E',   // Input fields border
      primaryColor: '#FFFFFF',      // Primary text
      secondaryColor: '#9A9AAE',    // Placeholder text
      borderColor: '#3A3A4E',       // General borders
      inverseColor: '#1A1A2E',      // Text on action buttons
      outlineColor: '#6C6CFF',      // Focus ring
      errorColor: '#FF6B6B',        // Error messages
      successColor: '#4ADE80',      // Success state
      disabledColor: '#4A4A5E',     // Disabled elements
      borderButtonRadius: 12,       // Button corner radius
      borderFormRadius: 8,          // Input field corner radius
    ),
  ),
  onResult: _handleResult,
)

5. Component type

Choose between the full Flow component or card-only mode:

// Card-only: shows just the card fields and Pay button (no radio selector)
CheckoutFlowWidget(
  config: CheckoutFlowConfig(
    publicKey: 'pk_sbox_xxx',
    paymentSessionId: 'ps_xxx',
    paymentSessionSecret: 'secret_xxx',
    componentType: CheckoutComponentType.card,
  ),
  onResult: _handleResult,
)
Type Description
CheckoutComponentType.flow Full Flow UI with payment method selector (default)
CheckoutComponentType.card Card-only fields with Pay button, no radio selector

6. Handle the result

CheckoutFlowResult is a sealed class with three subtypes:

Type Fields Description
CheckoutFlowSuccess paymentId Synchronous payment completed
CheckoutFlowError errorCode, message Payment failed or initialization error
CheckoutFlowCancelled — User cancelled the payment

Asynchronous payments

Some payment methods (e.g. 3DS, redirects) complete asynchronously. In this case, Checkout.com sends a webhook notification with data.metadata.cko_payment_session_id, and the customer is redirected to your success_url or failure_url.

API Reference

CheckoutFlowConfig

Parameter Type Required Default Description
publicKey String Yes — Your Checkout.com public API key
paymentSessionId String Yes — Payment session ID from server
paymentSessionToken String? No null Payment session token (legacy, optional since SDK v1.6+)
paymentSessionSecret String Yes — Payment session secret from server
environment CheckoutFlowEnvironment No sandbox sandbox or production
componentType CheckoutComponentType No flow flow or card
theme CheckoutFlowTheme? No null Custom theme (null = default light theme)

CheckoutFlowTheme

Parameter Type Default Description
actionColor String? #0B5FFF Pay button and link color
backgroundColor String? #FFFFFF Container background
borderColor String? SDK default General border color
disabledColor String? SDK default Disabled element color
errorColor String? SDK default Error message color
formBackgroundColor String? #FFFFFF Input field background
formBorderColor String? SDK default Input field border
inverseColor String? #FFFFFF Text on action buttons
outlineColor String? SDK default Focus ring color
primaryColor String? #000000 Primary text color
secondaryColor String? SDK default Placeholder/hint text
successColor String? SDK default Success state color
borderButtonRadius double? 8 Button corner radius
borderFormRadius double? 8 Form field corner radius

CheckoutFlowWidget

Parameter Type Required Description
config CheckoutFlowConfig Yes Payment session configuration
onResult ValueChanged<CheckoutFlowResult> Yes Callback for payment results
onReady VoidCallback? No Called when Flow UI is rendered
height double? No Widget height (default: 400)

CheckoutFlowEnvironment

Value Description
sandbox Test environment
production Live environment

Troubleshooting

Flow component not available

If you receive a CheckoutFlowError with code UNAVAILABLE, check that:

  • Your public key has the correct scopes
  • The payment session was created correctly
  • The currency/country combination is supported

Build errors on Android

Ensure your minSdkVersion is at least 21 and compileSdkVersion is at least 34.

Build errors on iOS

Ensure your deployment target is at least iOS 15.0 in your Xcode project settings.

Xcode 16+ / Xcode 26 build errors

If you see Unable to find module dependency: 'CheckoutComponentsSDK', this is related to Xcode's explicit module build feature. The plugin's podspec already sets SWIFT_ENABLE_EXPLICIT_MODULES => NO to work around this. If you still encounter issues, add the following to your ios/Podfile:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['SWIFT_ENABLE_EXPLICIT_MODULES'] = 'NO'
    end
  end
end

Contributing

Contributions are welcome! Please note that this is a community project — it is not maintained by Checkout.com. Before submitting a pull request, ensure your changes work on both Android and iOS.

Sponsors

This project is made possible thanks to the support of:

  • LBD — Digital solutions & software development
  • Transfeero — Global transfer and mobility platform

Interested in sponsoring this project? Get in touch.

License

MIT License. See LICENSE for details.

This project is not affiliated with Checkout.com. All trademarks belong to their respective owners.

Libraries

checkout_com_flow
Flutter plugin for Checkout.com Flow payment components.