💳 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

---

📦 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.googleapis.com/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,
  pollingInterval: 3.0, //seconds
  pollingTimeout: 360.0, //seconds
);

---

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': 'YOUR_SDK_CODE'},
        'transaction': {
          'reference_id': 'REF${DateTime.now().millisecondsSinceEpoch}',
          'account': 'YOUR_ACCOUNT',
          '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);

---

🌐 Internationalization (i18n)

This plugin and its example apps support multiple languages (English, Portuguese, Spanish).

For full setup instructions, see the Internationalization Guide.

---

🎨 Presentation Modes (BottomSheet / Fullscreen)

The unified field presentation_style controls how the checkout view appears.

Value	iOS Equivalent	Android Equivalent
'bottomsheet'	.bottomSheet	useBottomSheet = true
'fullscreen'	.fullscreen	useBottomSheet = false

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': 'YOUR_SDK_CODE'},
        'transaction': {
          'reference_id': 'REF123',
          'account': 'YOUR_ACCOUNT',
          '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
 │   ├─ views/
 │   │   └─ payment_view.dart
 │   ├─ viewmodels/
 │   │   └─ payment_viewmodel.dart
 │   ├─ mocks/
 │   │   ├─ mock_pix.dart
 │   │   ├─ mock_card.dart
 │   │   ├─ mock_bnpl.dart
 │   │   └─ mock_paypal.dart
 │   ├─ models/
 │   │   └─ payment_input.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:

Result Type	type field	Example
Success	processed	{ "data": { "referenceId": "...", "status": { "type": "APPROVED" } } }
Failure	failure	{ "error": { "code": "NETWORK", "message": "Timeout" } }
Canceled	canceled	{ "type": "canceled" }

---

🧾 License

This project is licensed under the MIT License.

---

🏷️ Plugin Version

Koin Payments Flutter Plugin v0.0.3

PaymentsFlutter.version == "0.0.3"

---

🧰 Useful Links

• 🔗 Android SDK
• 🍎 iOS SDK

---

Built by the Koin team.