💳 Koin Payments Flutter Plugin #

The Koin Payments Flutter Plugin provides a unified Flutter interface to integrate the Koin Checkout SDK for both Android and iOS platforms.

It allows you to initialize the SDK, build payment requests (PaymentRequest), and start checkout flows using PIX, Card, BNPL (Buy Now, Pay Later), and PayPal with a single cross‑platform API.

🧩 Features #

• ✅ Works with Flutter 3.10+ and Dart 3.0+
• 🪟 Supports BottomSheet and Fullscreen checkout presentations
• 💰 Payment methods: PIX, Credit Card, BNPL, PayPal
• 🧠 Uses the native Koin SDKs under the hood (iOS & Android)
• ⚙️ Simple initialization and strongly typed request mapping
• 🧪 Includes a complete example app

📦 Installation #

In your project pubspec.yaml:

dependencies:
  payments_flutter_plugin:
    git:
      url: https://github.com/koinlatam/payments-flutter-plugin.git
      ref: main

Then run:

flutter pub get

🔧 Android Setup #

1️⃣ Add Koin's Maven repository #

In your android/settings.gradle or android/build.gradle file (plugin and app):

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://koinlatam.github.io/koin-checkout-android/") }
        maven { url = uri("https://storage.flutter-io.cn/download.flutter.io") }
    }
}

2️⃣ Internet permission #

Make sure your app's manifest includes:

<uses-permission android:name="android.permission.INTERNET" />

3️⃣ Initialization #

You don’t need a custom Application class — the Flutter plugin’s PaymentsFlutter.initialize() method automatically initializes the Koin SDK for you.

🍎 iOS Setup #

1️⃣ Podfile #

Enable dynamic frameworks:

use_frameworks!
use_modular_headers!

2️⃣ Koin CocoaPods repository #

The iOS SDK (KoinPaymentCheckout) is fetched automatically by CocoaPods when installing the plugin.

Run:

cd ios
pod install

3️⃣ Initialization #

On iOS, initialization is also handled by PaymentsFlutter.initialize().

🚀 Basic Usage #

1️⃣ Initialize the SDK #

await PaymentsFlutter.initialize(
  key: 'sk_your_private_key_here',
  paypalClientID: 'your_paypal_client_id',
  isHomolog: true, // true = sandbox
  enableLogs: true,
  maxRetries: 3,
  poolingInterval: 2000,
  poolingTimeout: 600000,
);

2️⃣ Build a payment request #

You can use mocks (from the example) or build manually.

final input = {
  'input': {
    'payment': {
      'data': {
        'country_code': 'BR',
        'store': {'code': 'ILIA_SDK'},
        'transaction': {
          'reference_id': 'REF${DateTime.now().millisecondsSinceEpoch}',
          'account': '1383543PI',
          'amount': {'currency_code': 'BRL', 'value': 250.0},
        },
        'payer': {
          'email': 'user@email.com',
          'document': {'type': 'cpf', 'number': '29517016085'},
          'full_name': 'John Doe'
        },
        'payment_method': {'code': 'PIX'},
        'presentation_style': 'bottomsheet', // or 'fullscreen'
      },
      'kind': 'pix',
    },
  },
};

3️⃣ Start the checkout #

final result = await PaymentsFlutter.startCheckout(input: input);
print(result);

🎨 Presentation Modes (BottomSheet / Fullscreen) #

The unified field presentation_style controls how the checkout view appears.

The plugin automatically maps presentation_style → useBottomSheet on Android.

💡 Full Example #

await PaymentsFlutter.initialize(
  key: 'sk_your_private_key_here',
  isHomolog: true,
  enableLogs: true,
);

final input = {
  'input': {
    'payment': {
      'data': {
        'country_code': 'BR',
        'store': {'code': 'ILIA_SDK'},
        'transaction': {
          'reference_id': 'REF123',
          'account': '1383543PI',
          'amount': {'currency_code': 'BRL', 'value': 250.0},
        },
        'payer': {
          'email': 'user@email.com',
          'document': {'type': 'cpf', 'number': '29517016085'},
          'full_name': 'John Doe',
        },
        'payment_method': {'code': 'PIX'},
        'presentation_style': 'bottomsheet',
      },
      'kind': 'pix',
    },
  },
};

final result = await PaymentsFlutter.startCheckout(input: input);
print(result);

🧠 Example Project Structure #

example/
 ├─ lib/
 │   ├─ main.dart              # Main screen
 │   ├─ viewmodels/
 │   │   └─ payment_viewmodel.dart
 │   ├─ mocks/
 │   │   ├─ mock_pix.dart
 │   │   ├─ mock_card.dart
 │   │   ├─ mock_bnpl.dart
 │   │   └─ mock_paypal.dart
 ├─ android/
 │   └─ build.gradle, settings.gradle (with Koin repo)
 ├─ ios/
 │   └─ Podfile, Podfile.lock (links Koin iOS SDK)

🧪 Checkout Results #

The startCheckout method returns a Map<String, dynamic> describing the result:

🧾 License #

This project is licensed under the MIT License.

🏷️ Plugin Version #

Koin Payments Flutter Plugin v0.0.1

PaymentsFlutter.version == "0.0.1"

🧰 Useful Links #

• 🔗 Android SDK
• 🍎 iOS SDK
• 🧑‍💻 Flutter Example

Built by the Koin team.