Payment Flows

The Android SDK makes it easy to integrate payment flows into your Android app.

Additional resources

• See Choose the right integration for you if you're unsure which flow to follow.
• Access the Release notes or the Yuno Android SDK repository to verify the latest SDK version available.

Requirements

• Minimum SDK Version: minSdkVersion 21 or above
• Java: Java 8 enabled
• AndroidX: Use AndroidX instead of older support libraries
• Android Gradle Plugin: 4.0.0 or above
• ProGuard: 6.2.2 or above
• Kotlin Gradle Plugin: 1.4.0 or above
• ELF Page Size Support: Compliant with Google's 16 KB ELF page alignment requirements (Android 15 / ARMv9 ready)
• Active Yuno account
• Yuno API credentials (obtain from the Yuno Dashboard → Developers > Credentials)
• Create a checkout_session and the payment via the API; create a customer using the Create customer endpoint before creating a payment

Include the library in your project

The first step is always including the library in your project; this step is performed regardless of which integration type you choose. Add the Yuno Android SDK to your project through Gradle. Add the repository source and dependency:

maven { url "https://yunopayments.jfrog.io/artifactory/snapshots-libs-release" }

dependencies {
    implementation 'com.yuno.payments:android-sdk:{last_version}'
}

Once Step 1 is complete, continue with your desired integration.

Basic flows

• Full (Android): Complete control with backend support and full customization options
• Seamless (payment Android): Fastest integration with pre-built UI components

Advanced flows

• Lite (Android): Lightweight integration allowing you to control the UI and payment methods list, as well as backend support
• Headless (Android): Full checkout experience customization without requiring PCI compliance

Parameters

For the full list of parameters and YunoConfig details, see the Android SDK Common Reference.

Full (Android)

Implement Full (Android): customizable UI, payment method management, fraud prevention, and checkout flows. More feature-rich than Headless, which focuses on core payment processing. See Requirements above.

Step 1: Include the library in your project

Follow the steps in Include the library in your project above.

Step 2: Initialize SDK with the public key

Retrieve your public API keys from the Yuno Dashboard.

If you haven't implemented a custom application, create one. In the onCreate() method of your application class, call the initialize function (Yuno.initialize):

class CustomApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    Yuno.initialize(
      this,
      "<your-public-api-key>",
      config = YunoConfig(),
    )
  }
}

See the credentials page for more information. Use the data class YunoConfig to customize the SDK's behavior. Include this configuration when calling Yuno.initialize(). The available options are:

data class YunoConfig(
    val cardFlow: CardFormType = CardFormType.ONE_STEP,
    val saveCardEnabled: Boolean = false,
    val cardFormDeployed: Boolean = false,
    val language: YunoLanguage? = null,
    val styles: YunoStyles? = null,
    val cardNumberPlaceholder: String? = null, // Optional: Custom placeholder text for card number field
    val hideCardholderName: Boolean? = null // Optional: Set to true to hide cardholder name field
)

YunoConfig options

Customization options:

Update your manifest to use your application:

<application android:name=".CustomApplication"></application>

Step 3: Create the checkout session

Each payment requires a new checkout_session. Use the Create checkout session endpoint to create one; use that session to initiate the payment.

If your payment flow sends users to an external browser (e.g., for 3DS authentication or bank redirects), set the callback_url when creating your checkout session. See Handle external browser return (callback_url) for details.

Step 4: Start the checkout process

Call the startCheckout method inside the onCreate() function of the activity that initializes the SDK to start a new payment process with Full (Android):

startCheckout(
  checkoutSession: "checkout_session",
  countryCode: "country_code_iso",
  callbackPaymentState: ((String?) -> Unit)?,
  merchantSessionId: String? = null
)

See Parameters. The following are the possible states returned by the callbackPaymentState:

const val PAYMENT_STATE_SUCCEEDED = "SUCCEEDED"
const val PAYMENT_STATE_FAIL = "FAIL"
const val PAYMENT_STATE_PROCESSING = "PROCESSING"
const val PAYMENT_STATE_REJECT = "REJECT"
const val PAYMENT_STATE_INTERNAL_ERROR = "INTERNAL_ERROR"
const val PAYMENT_STATE_STATE_CANCELED_BY_USER = "CANCELED"

Possible states:

Payment status validation

This section explains how the SDK handles payment status when users cancel or leave payment flows, and how the SDK status relates to the backend payment status in these scenarios.

Sync payment methods (Google Pay)

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

• SDK Status: Returns CANCELED (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 (clicks X) 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.

Step 5: Add the SDK view to the checkout

Use the PaymentMethodListViewComponent to display the available payment methods when implementing Full (Android) with Jetpack Compose. This component provides callbacks to notify your app when to enable or disable the pay button, and when an enrolled payment method is successfully removed.

Component signature

@Composable
fun PaymentMethodListViewComponent(
    activity: Activity,
    modifier: Modifier? = null,
    onPaymentSelected: (Boolean) -> Unit,
    onUnEnrollSuccess: (Boolean) -> Unit = {}
)

Component options

• activity: Activity: Current Activity where the component is hosted. Required for payment flows.
• modifier: Modifier? (optional): Layout and appearance (e.g. padding, spacing). Defaults to null.
• onPaymentSelected: (Boolean) -> Unit: Invoked when a payment method is selected or deselected (true = method selected, enable pay button; false = none selected).
• onUnEnrollSuccess: (Boolean) -> Unit (optional): Invoked when a stored payment method is successfully removed.

Example

val coroutineScope = rememberCoroutineScope()
val snackbarHostState = remember { SnackbarHostState() }
var paymentMethodIsSelected by remember { mutableStateOf(false) }

Column(
    modifier = Modifier
        .weight(1f)
        .verticalScroll(rememberScrollState())
) {
    PaymentMethodListViewComponent(
        activity = activity,
        onPaymentSelected = { isSelected ->
            paymentMethodIsSelected = isSelected
        },
        onUnEnrollSuccess = { success ->
            if (success) {
                coroutineScope.launch {
                    snackbarHostState.showSnackbar(
                        message = "Your payment method has been removed",
                    )
                }
            }
        },
    )
}

❗

Important

Always wrap the component in a Column with .verticalScroll(rememberScrollState()). Without this, the list of payment methods may not render or scroll properly when there are multiple methods available.

Step 6: Initiate the payment process

Call the startPayment() method to start a payment process:

startPayment(
    showStatusYuno: Boolean,
    callbackOTT: (String?) -> Unit = this::onTokenUpdated,
    callBackTokenWithInformation: (OneTimeTokenModel?) -> Unit = this::onTokenComplete
)

Options

Configure the payment with the following options:

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

After the customer fills out the requested data in Yuno's payment forms, you will obtain the one-time token, a required parameter to create a payment using the Yuno API.

The one-time token will be shared by Yuno using the callbackOTT function you provided in Step 6 when initiating the payment. The one-time token will be available in the onActivityResult.

A loader can be shown while the one-time token is generated. Use Yuno's default or implement your own with the required configuration.

Step 8: Create the payment

After receiving the one-time token from Step 7, create the payment using the Create payment endpoint. Use the checkout_session from Step 3 and the one-time token to create the payment.

The response from the Create payment endpoint will include the parameter sdk_action_required, which defines if additional actions are required to finish the payment based on the payment type.

🚧

Continue Payment Method Integration

Yuno requires you integrate the continuePayment method of the SDK after the payment is created because certain asynchronous payment methods require additional customer actions to complete. The API will inform you of this scenario via the sdk_action_required field of the response, which will be returned as true. The yuno.continuePayment() function will display additional screens to customers, where they can carry out the necessary actions to complete the payment without you needing to handle every scenario.

Step 9: Continue payment

Yuno requires integrating the SDK's continuePayment method after the payment is created, as certain asynchronous payment methods require additional customer actions to complete. The response from the Create payment endpoint, from Step 8, will include a sdk_action_required field. If it returns TRUE, you need to call the continuePayment() function to show additional screens that allow the customer to complete the payment. Otherwise, this step is not necessary. Call the continuePayment method:

continuePayment(
    showPaymentStatus: Boolean = true,
    checkoutSession: String? = null,
    countryCode: String? = null,
    callbackPaymentState: ((String?) -> Unit)? = null
)

To show your payment status screens, send FALSE in the showPaymentStatus parameter. Then, get the payment state by callback.

Complementary features

For styling, themes, form options, and additional configurations (including Click to Pay with Passkey), see SDK customizations.

Seamless (payment Android)

Seamless (payment Android) for payments.

Recommended: Use Seamless (payment Android) for pre-built UI and customization.

This SDK is ideal for merchants who:

• Want control over the payment flow while leveraging pre-built UI components
• Need to customize the payment experience while maintaining PCI compliance
• Require a balance between implementation speed and customization

Seamless (payment Android) includes features like:

• Pre-built payment UI components with customization options
• Multiple payment method support
• Advanced payment status handling
• Comprehensive error management

For merchants requiring complete UI control or more advanced features, consider using our Full instead.

See Requirements above.

Step 1: Create a customer

Create a customer using the Create customer endpoint before initiating payments. This step is required to:

• Identify the person making the payment
• Enable saved card functionality (if enabled)
• Track payment history

The customer ID returned from this endpoint will be used when creating the checkout_session.

Step 2: Create a checkout session

Create a new checkout_session using the Create checkout session endpoint to initialize the payment flow. Make sure to:

• Include the customer ID obtained from the previous step
• Store the returned checkout_session ID for use in Step 5 of the integration

💳

Auth vs capture

Control auth vs capture by sending payment_method.detail.card.capture in the checkout session: false = authorize only, true = capture immediately.

Checkout session options

🚧

Checkout session usage

The checkout_session is unique for each payment attempt and cannot be reused.

Follow the steps in Include the library in your project above.

Step 3: Configure permissions

The Yuno SDK requires network permissions. Ensure the INTERNET permission is included in your AndroidManifest.xml:

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

Step 4: Initialize SDK

Retrieve your public API keys from the Yuno Dashboard.

If you haven't implemented a custom application, create one. In the onCreate() method of your application class, call the initialize function (Yuno.initialize):

class CustomApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Yuno.initialize(
            this,
            PUBLIC_API_KEY,
            config = YunoConfig()
        )
    }
}

Use the YunoConfig data class to set additional configurations. Options:

Example (YunoConfig):

data class YunoConfig(
    val cardFlow: CardFormType = CardFormType.ONE_STEP,
    val saveCardEnabled: Boolean = false,
    val language: YunoLanguage? = null,
  	val styles: YunoStyles? = null,
    val cardNumberPlaceholder: String? = null, // Optional: Custom placeholder text for card number field
    val hideCardholderName: Boolean? = null // Optional: Set to true to hide cardholder name field
)

Step 5: Start checkout

Call the startCheckout method in the onCreate() function of the activity that integrates the SDK to initiate a new payment process with Seamless (payment Android):

startCheckout(
  checkoutSession: "checkout_session",
  country_code: "US",
  callbackPaymentState: ((String?) -> Unit)?,
  merchantSessionId: String? = null
)

The possible payment states returned by callbackPaymentState are:

const val PAYMENT_STATE_SUCCEEDED = "SUCCEEDED"
const val PAYMENT_STATE_FAIL = "FAIL"
const val PAYMENT_STATE_PROCESSING = "PROCESSING"
const val PAYMENT_STATE_REJECT = "REJECT"
const val PAYMENT_STATE_INTERNAL_ERROR = "INTERNAL_ERROR"
const val PAYMENT_STATE_STATE_CANCELED_BY_USER = "CANCELED"

Possible states:

Payment status validation

This section explains how the SDK handles payment status when users cancel or leave payment flows, and how the SDK status relates to the backend payment status in these scenarios.

Sync payment methods (Google Pay)

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

• SDK Status: Returns CANCELED (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 (clicks X) 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.

Step 6: Get payment one-time token (OTT)

Call the method startPaymentSeamlessLite to start a payment process:

startPaymentSeamlessLite(
    paymentSelected: PaymentSelected,
    callbackPaymentState: ((String?) -> Unit)?,
    showPaymentStatus: Boolean,
)

Parameters to start the payment:

You will receive the payment status via callbackPaymentState, which will indicate whether the payment was successful or if an issue occurred.

Step 7: Create payment

Call the method startPaymentSeamlessLite with the selected payment method to complete the payment process:

startPaymentSeamlessLite(
    paymentSelected: PaymentSelected,
    callbackPaymentState: ((String?) -> Unit)?,
    showPaymentStatus: Boolean,
)

Complementary features

For styling, themes, form options, and additional configurations, see SDK customizations.

Lite (Android)

Lite (Android) offers a streamlined integration process with essential payment functionality. Ideal for merchants who:

• Need a quick implementation with minimal customization requirements
• Want to focus primarily on card payment processing
• Prefer a ready-to-use UI that handles the payment flow

Lite (Android) includes core features like:

• Pre-built payment UI components
• Card payment processing
• Basic payment status handling
• Essential error management

For merchants requiring more advanced features like multiple payment methods, custom UI, or advanced fraud prevention, consider using our Full instead.

See Requirements above.

Step 1: Create a customer

Create a customer using the Create customer endpoint before initiating payments. This step is required to:

• Identify the person making the payment
• Enable saved card functionality (if enabled)
• Track payment history

The customer ID returned from this endpoint will be used when creating the checkout_session.

Step 2: Create a checkout session

Create a new checkout_session using the Create checkout session endpoint to initialize the payment flow. Make sure to:

• Include the customer ID obtained from the previous step
• Store the returned checkout_session ID for use in later steps
• Remember that the checkout_session is unique for each payment attempt and cannot be reused

🚧

External Browser Return Handling

If your payment flow sends users to an external browser (for example, for 3DS authentication or bank redirects), make sure to set the callback_url when creating your checkout session. For a step-by-step guide on handling the return to your app, see Handle external browser return (callback_url).

Follow the steps in Include the library in your project above.

Step 3: Initialize SDK with the public key

Initialize the SDK:

1. Get your public API keys from the Yuno Dashboard
2. Create a custom application class if you don't have one
3. Initialize the SDK by calling Yuno.initialize() in your application's onCreate() method, passing your API key and configuration:

class CustomApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    Yuno.initialize(
      this,
      PUBLIC_API_KEY,
      config = YunoConfig(),
    )
  }
}

Use the data class YunoConfig to customize the SDK's behavior. Include this configuration when calling Yuno.initialize(). For example:

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

Step 4: Start checkout with Lite

After initializing the SDK and creating the checkout session, you can start the payment process using Lite (Android). Use startCheckout to configure the Lite flow and then mount the payment UI.

startCheckout(
  checkoutSession: "checkout_session",
  countryCode: "US",
  callbackPaymentState: { paymentState ->
      // Handle payment state: SUCCEEDED, FAIL, PROCESSING, REJECT, INTERNAL_ERROR, CANCELED
  }
)

Then call the Lite mounting method to present the flow:

startPayment(
    showStatusYuno = true,
    callbackOTT = { ott ->
        // Send OTT to your backend to create the payment
    }
)

A loader can be shown while the one-time token is generated. Use Yuno's default or implement your own with the required configuration.

Step 5: Create the payment

After receiving the one-time token from Lite (Android), create the payment using the Create payment endpoint. Use the checkout_session from the previous steps and the one-time token to create the payment.

The response from the Create payment endpoint will include the parameter sdk_action_required, which defines if additional actions are required to finish the payment based on the payment type. If sdk_action_required is true, you must call continuePayment() to complete the flow.

Headless (Android)

Yuno Headless Android SDK for payments.

Headless (Android) is ideal for merchants who:

• Need full control over the payment UI and user experience
• Want to build custom payment flows
• Require advanced integration capabilities

Headless (Android) includes core features like:

• Direct API access for payment processing
• Token generation for payment methods
• 3DS authentication handling
• Fraud prevention data collection

For merchants preferring a pre-built UI solution, consider using our Full or Lite instead.

See Requirements above.

Step 1: Create a customer

Create a customer using the Create customer endpoint before initiating payments. This step is required to:

• Identify the person making the payment
• Enable saved payment method functionality (if enabled)
• Track payment history

The customer ID returned from this endpoint will be used when creating the checkout_session.

Step 2: Create a checkout session

Create a new checkout_session using the Create checkout session endpoint to initialize the payment flow. Make sure to:

• Include the customer ID obtained from the previous step
• Store the returned checkout_session ID for use in later steps

The checkout_session is unique for each payment attempt and cannot be reused.

Follow the steps in Include the library in your project above.

Step 3: Initialize Headless with the public key

Import Yuno and provide a valid PUBLIC_API_KEY to initialize Headless (Android):

class CustomApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    Yuno.initialize(
      this,
      PUBLIC_API_KEY,
      config = YunoConfig(),
    )
  }
}

Step 4: Start the checkout process

Call the apiClientPayment function after your customer selects a payment method to start the checkout process. This function requires configuration parameters and initiates the collection of information needed for 3DS authentication and fraud prevention tools configured in your routing.

val apiClientPayment = yuno.apiClientPayment(
  country_code = "US",
  checkout_session = "checkout_session_id"
)

From there you can generate a one-time token using apiClientPayment.generateToken(...), handle 3DS challenges, and continue payments as documented in the Headless Android SDK reference.

Common reference

For full parameter and customization details, see the Android SDK Common Reference.