Flutter Lite

This guide walks you through integrating Yuno's Flutter SDK Lite payment and enrollment flows into your project.

Requirements

Before you start, make sure your project meets these requirements:

• Flutter SDK installed (Dart included).
• iOS 14.0 or above.
• Android minSdkVersion 21 or above.
• Java 8 enabled and AndroidX enabled.
• Android Gradle plugin 4.0.0 or above.
• Proguard 6.2.2 or above.
• Kotlin Gradle plugin 1.4.0 or above.
• FlutterFragmentActivity for MainActivity on Android.

Adding the SDK to your project

This section applies to both Payment and Enrollment flows. Complete these steps before implementing either flow.

Flutter Package

Add the Yuno package to your Flutter project:

flutter pub add yuno

Android Configuration

Add the Yuno Maven repository to your project-level android/build.gradle:

allprojects {
  repositories {
    google()
    mavenCentral()
    maven { url "https://yunopayments.jfrog.io/artifactory/snapshots-libs-release" }
  }
}

Use FlutterFragmentActivity in MainActivity.kt:

class MainActivity: FlutterFragmentActivity()

Create a custom Application and initialize the native SDK:

import android.app.Application
import com.yuno_flutter.yuno_sdk_android.YunoSdkAndroidPlugin

class MyApp : Application() {
  override fun onCreate() {
    super.onCreate()
    YunoSdkAndroidPlugin.initSdk(this, "YUNO_API_KEY")
  }
}

Then register the application class in AndroidManifest.xml:

<application
  android:name=".MyApp">

iOS Configuration

No additional iOS-specific configuration required beyond the Flutter package installation. iOS appearance customization is configured through IosConfig during SDK initialization (see Customizations section).

Payment

Step 1: Create a customer and checkout session

Before initiating a payment through the SDK, you need to create a customer and checkout session using Yuno's server-side API. The customer represents the person making the payment, while the checkout session contains transaction details like amount, currency, and available payment methods. These are created in your backend to ensure security and prevent client-side tampering.

Create a customer using the Create customer endpoint. This customer is required for checkout sessions and saved cards.

Create a new checkout_session using the Create checkout session endpoint. Keep the returned checkout_session ID for use in Step 4.

Step 2: Initialize the SDK

Initialize the Yuno SDK in your Flutter app before any payment or enrollment operations. This configures the SDK with your API key and sets regional, language, and UI preferences that will apply throughout the payment flow.

Make sure Yuno.init() is called before runApp in your main.dart file:

await Yuno.init(
  apiKey: 'YOUR_PUBLIC_API_KEY',
  countryCode: 'CO',
  yunoConfig: const YunoConfig(),
  iosConfig: const IosConfig(),
);

See Yuno.init, YunoConfig, and IosConfig parameters for detailed configuration options.

Step 3: Start the checkout process

Set up a payment listener in your widget tree to receive payment events and status updates from the SDK. The listener must be placed in the widget tree before initiating the payment flow so it can capture the one-time token and payment status.

Use YunoPaymentListener or YunoMultiListener to receive the OTT from the SDK:

YunoPaymentListener(
  listener: (context, state) {
    final ott = state.token;
    if (ott.isNotEmpty) {
      // Send ott to your backend to create the payment
    }
  },
  child: YourWidget(),
)

Alternatively, use YunoMultiListener to handle both payment and enrollment flows:

YunoMultiListener(
  paymentListener: (context, state) {
    final ott = state.token;
    if (ott.isNotEmpty) {
      // Send ott to your backend to create the payment
    }
  },
  enrollmentListener: (context, state) {
    final status = state.enrollmentStatus;
    // Handle enrollment status updates
  },
  child: YourWidget(),
)

Payment status values

The SDK returns different transaction states through the YunoStatus enum. The following table describes each state:

Step 4: Initiate payment

Start the Lite payment flow by calling startPaymentLite with the selected payment method. In the Lite SDK, you are responsible for displaying available payment methods and capturing the user's selection. The SDK handles the payment form and processing for the selected method.

await Yuno.startPaymentLite(
  arguments: StartPayment(
    checkoutSession: checkoutSessionId,
    methodSelected: const MethodSelected(
      paymentMethodType: 'CARD',
    ),
  ),
);

The Lite payment flow does not render a payment method list. Your app must show the available methods and pass the selected paymentMethodType (and vaultedToken if applicable).

See StartPayment and MethodSelected parameters for detailed options.

Step 5: Get the OTT (one-time token)

After the user completes the payment form, the SDK generates a one-time token (OTT) that securely represents the payment details. This token is delivered to your YunoPaymentListener callback and must be sent to your backend to create the actual payment.

The OTT is available in the listener you set up in Step 3:

listener: (context, state) {
  final ott = state.token;
  if (ott.isNotEmpty) {
    // Send ott to your backend to create the payment
  }
}

Step 6: Create the payment

Use the one-time token from Step 5 to create the payment in your backend. Call the Create payment endpoint from your server with:

• one_time_token from Step 5
• checkout_session from Step 1

The API response will indicate whether additional actions are required using the sdk_action_required field.

Step 7: Continue payment

Some payment methods require additional customer actions to complete the transaction, such as 3D Secure authentication or bank redirects. When the Create Payment API response includes sdk_action_required: true, you must call continuePayment to display these additional screens to the user.

If the API response includes sdk_action_required: true, call:

await Yuno.continuePayment(showPaymentStatus: true);

This method handles asynchronous payment flows automatically, including authentication challenges, redirect pages, and payment confirmations.

Payment status validation

The SDK manages the relationship between frontend SDK status and backend payment status when users interact with payment flows. Understanding this distinction helps you handle payment states correctly in your application.

Sync payment methods (Apple Pay and Google Pay)

For synchronous payment methods like Apple Pay and Google Pay, when a user cancels or closes the wallet UI before a payment service provider (PSP) response is received:

• SDK Status: Returns cancelByUser (CANCELLED_BY_USER)
• Backend payment status: Remains PENDING until PSP timeout or merchant cancellation
• Important: The SDK will not return reject or processing in this scenario

This ensures that the backend payment remains in a pending state and can be properly handled by the merchant's system.

Async payment methods (PIX and QR-based methods)

For asynchronous payment methods like PIX, when a user closes the QR code window before completing the payment:

• SDK Status: Returns processing, optionally with a sub-status such as CLOSED_BY_USER
• Backend payment status: Remains PENDING and the QR code remains valid until expiry
• Checkout session reuse: Re-opening the same checkout session can display the same valid QR code
• No Automatic Cancellation: The PIX payment is not automatically cancelled when the user closes the QR window

This behavior allows users to return to the payment flow and complete the transaction using the same QR code before it expires.

Expired async payments

If a PIX QR code expires naturally:

• Backend Status: Updated to EXPIRED
• SDK Status: SDK callbacks and polling endpoints return EXPIRED consistently

This ensures merchants receive accurate status information when a payment method has expired.

Enrollment

Step 1: Create customer and customer session

Before enrolling a payment method, create a customer and customer session in your backend. The customer session is specifically designed for enrollment flows and associates the enrolled payment method with the customer for future use.

Create a customer and a customer_session using the Create customer session endpoint. Keep the returned customer_session ID for use in Step 4.

Step 2: Initialize the SDK

If you haven't already initialized the SDK for payment flows, initialize it now with your API key and configuration preferences. This step can be shared between payment and enrollment flows.

Make sure Yuno.init() is called before any enrollment operations:

await Yuno.init(
  apiKey: 'YOUR_PUBLIC_API_KEY',
  countryCode: 'CO',
  yunoConfig: const YunoConfig(),
  iosConfig: const IosConfig(),
);

See Yuno.init, YunoConfig, and IosConfig parameters for detailed configuration options.

Step 3: Start enrollment process

Set up an enrollment listener in your widget tree to receive enrollment status updates from the SDK. The listener captures the enrollment result and any errors that occur during the process.

Use YunoEnrollmentListener or YunoMultiListener:

YunoEnrollmentListener(
  listener: (context, state) {
    final status = state.enrollmentStatus;
    // Handle status updates
  },
  child: YourWidget(),
)

Step 4: Initiate enrollment

Start the enrollment flow by calling enrollmentPayment with the customer session. The SDK will display the appropriate enrollment form for the payment method the user wants to save.

await Yuno.enrollmentPayment(
  arguments: EnrollmentArguments(
    customerSession: customerSessionId,
    showPaymentStatus: true,
  ),
);

See EnrollmentArguments parameters for detailed options.

Step 5: Listen for enrollment status

Monitor the enrollment status through the listener you configured in Step 3. The status indicates whether the payment method was successfully enrolled, failed, or requires additional actions.

The enrollment status is delivered to your YunoEnrollmentListener callback:

listener: (context, state) {
  final status = state.enrollmentStatus;
  // Handle enrollment completion, errors, or user cancellation
}

Step 6: Handle deep links (optional)

Some enrollment flows redirect users to external authentication pages (like bank portals) and return to your app via deep links. This step is only required if you're enrolling payment methods that use external authentication or verification.

If the enrollment flow uses a deep link to return to your app on iOS:

1. Configure your URL scheme in Info.plist to match the callback_url used in the customer_session.
2. Pass the URL to the SDK:

await Yuno.receiveDeeplink(url: uri);

For Android deep link configuration, refer to the Android deep linking documentation.

Parameters

The following parameters are used in the integration flows above.

Yuno.init

YunoConfig

IosConfig

Appearance (iOS)

StartPayment (Lite)

MethodSelected

EnrollmentArguments

Customizations

You can customize SDK behavior and appearance using the configuration options:

• YunoConfig for language, card flow render mode, save card, and loader handling
• IosConfig.appearance for iOS UI styling
• Android styling through native configuration (see below)

iOS Customization

iOS appearance is fully customizable through the IosConfig.appearance parameter in Yuno.init(). You can modify visual styling to match your brand identity, including colors, fonts, and button designs.

Available iOS Customization Options

Note: When using Color(0xFF...) for iOS appearance customization, you must add import 'dart:ui'; at the top of your file.

For more iOS customization options, see SDK Customizations (iOS).

Android Customization

For Android, the Flutter SDK leverages the native Android SDK's styling system. Customization is performed in the native Android layer using Kotlin/Java code when initializing the SDK through YunoSdkAndroidPlugin.initSdk().

YunoConfig (Android)

The Android SDK supports comprehensive styling through the YunoConfig data class:

data class YunoConfig(
    val cardFlow: CardFormType = CardFormType.ONE_STEP,
    val saveCardEnabled: Boolean = false,
    val language: YunoLanguage? = null,
    val styles: YunoStyles? = null
)

YunoStyles

Control the visual appearance of SDK components:

data class YunoStyles(
    val buttonStyles: YunoButtonStyles? = null,
    val fontFamily: FontFamily? = null
)

YunoButtonStyles

Fine-tune button appearance with these options:

data class YunoButtonStyles(
    val backgroundColor: Color? = null,
    val contentColor: Color? = null,
    val cornerRadius: Dp? = null,
    val elevation: Dp? = null,
    val padding: Dp? = null,
    val fontFamily: FontFamily? = null,
    val fontSize: TextUnit? = null,
    val fontStyle: FontStyle? = null
)

Configure styles in your Application class during SDK initialization in MyApp.kt. For more Android customization options including XML themes and drawable customization, see SDK Customizations (Android).

Environment variables (recommended)

Use --dart-define to avoid hardcoding keys:

flutter run --dart-define="YUNO_API_KEY=apiKey"

Then read it in Dart:

const apiKey = String.fromEnvironment('YUNO_API_KEY', defaultValue: '');

If you also need the key on Android native side, map dart-defines into BuildConfig and read BuildConfig.YUNO_API_KEY in MyApp (see the Flutter SDK README for the full snippet).

Troubleshooting

Notes

• The Lite payment flow requires you to render the payment method list and pass the selected paymentMethodType.
• Use YunoPaymentListener/YunoEnrollmentListener to receive OTT/status updates and drive backend calls.

Supported languages

The Flutter SDK supports the following YunoLanguage values:

en (English), es (Spanish), pt (Portuguese), ms (Malay), id (Indonesian), th (Thai), ar (Arabic).