Migration guide

// Before — manual hop was required
provider.submitTransaction(transaction) { transaction, error in
    DispatchQueue.main.async {
        self.updateUI(with: transaction, error: error)
    }
}


// After — the callback already runs on the main thread
provider.submitTransaction(transaction) { transaction, error in
    self.updateUI(with: transaction, error: error)   // safe
}

Migrating to 8.0.0

Overview

Migrating to 8.0.0 involves updating your project to align with the latest Android platform requirements and development tooling. This release introduces support for Android API Level 36 (Android 16), upgrades the Kotlin and Gradle ecosystem, refreshes all major dependencies to their latest stable versions, and includes an internal update to the onNewIntent() method signature.

These changes improve platform compatibility, build performance, security, and long-term maintainability while ensuring readiness for future Android releases.

What's Changing?

• Kotlin updated to 2.2.0.
• Android Gradle Plugin (AGP) updated to 8.13.0.
• Gradle updated to 8.14.5.
• compileSdkVersion and targetSdkVersion updated to Android API Level 36 (Android 16).
• All dependencies updated to their latest stable versions.
• Internal update to the onNewIntent() method signature.

Benefits

• Android 16 Support: Full compatibility with the latest Android devices and operating system features.
• Better Performance and Stability: Improved Kotlin version and updated dependency stack.
• Improved Build Experience: Faster and more reliable builds using the latest Gradle and Android Gradle Plugin versions.
• Security and Maintenance: Latest dependency updates, bug fixes, and security patches.
• Future Readiness: Aligned with upcoming Android platform requirements and best practices.

Steps

To ensure a smooth transition to the updated library, we recommend the following steps:

1. Update your development environment

• Upgrade Android Studio to Narwhal (2025.1.1) or later.
• Update your Gradle distribution to gradle-8.14.5.
• Ensure your JDK is set to Java 17 (required for AGP 8.13.0).

2. Update your project configuration

• Set sourceCompatibility and targetCompatibility to JavaVersion.VERSION_17.
• Set compileSdkVersion and targetSdkVersion to 36.
• Set kotlinOptions { jvmTarget = "17" }.

Example configuration:

android {
    compileSdkVersion 36

    defaultConfig {
        targetSdkVersion 36
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}

Android Gradle Plugin

Update Android Gradle Plugin (AGP), in project-level build.gradle file, update the android build gradle dependency to:

dependencies {
    classpath "com.android.tools.build:gradle:8.13.0"
}

In the gradle-wrapper.properties file, update the distributionUrl to:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.5-bin.zip

In your project-level build.gradle file, if you are using Kotlin, update the Kotlin version to 2.2.0

buildscript {
    ext.kotlin_version = "2.2.0"
}

3. Upgrade edge-to-edge design principles for Android 16

Applications targeting Android API Level 36 should adhere to edge-to-edge design principles. This helps ensure a modern user experience and proper use of the available screen space on newer Android devices.

Please refer to the official Android documentation for implementation details:

https://developer.android.com/develop/ui/views/layout/edge-to-edge?utm_source=android-studio-app&utm_medium=app target="_blank"> Edge-to-Edge Design Guidelines

4. Handle onNewIntent() signature change (if applicable)

The SDK now uses AppCompat versions that require a non-null Intent parameter in the onNewIntent() callback.

This change only affects applications that explicitly override the onNewIntent() method. Most integrations will not require any code changes.

If your application overrides onNewIntent() in any Activity, update the method signature as shown below.

If you are using Java

Before

@Override
protected void onNewIntent(@Nullable Intent intent) {
    super.onNewIntent(intent);
}

After (required)

@Override
protected void onNewIntent(@NonNull Intent intent) {
    super.onNewIntent(intent);
}

If you are using Kotlin

Before

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
}

After

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
}

5. Update dependencies

Update all Android, AndroidX, testing, and third-party dependencies to their latest stable versions to ensure compatibility with Android API Level 36 and the updated SDK stack.

Testing

Test your application with the updated library in a staging environment to identify any compatibility issues early.

Testing should include:

• Staging Environment: Test your application with the updated configuration in a staging environment before production deployment.
• Device Coverage: Test on multiple devices ranging from the minimum Android API level supported by your application up to Android API Level 36.
• Functional Testing: Verify that all application features, payment flows, and checkout scenarios work as expected.
• Performance Testing: Assess application startup performance, payment processing, and overall responsiveness with the updated SDK.
• Regression Testing: Ensure that existing functionality continues to work correctly after the migration.

Summary

Migrating to 8.0.0 ensures compatibility with Android 16, introduces the latest Kotlin and build tooling updates, improves overall stability and performance, and keeps your application aligned with modern Android development practices.

We recommend completing all migration and validation activities in a staging environment before deploying the updated SDK to production.

Migrating to 7.0.0

Migrating to 7.0.0 consist of two stages

1. Migration Guide from JDK 11 to JDK 17
2. Migration Guide from Android API Level 33 to API Level 35

1. Migration Guide from JDK 11 to JDK 17

Overview

Migrating from JDK 11 to JDK 17 involves updating your project to leverage the latest features, performance improvements, and security enhancements provided by Java 17. This guide will walk you through the necessary steps to ensure a smooth transition.

Steps

1. Download JDK 17

   First, download JDK 17 from Android Studio settings:

   • Go to File -> Settings -> Build, Execution, Deployment -> Build Tools -> Gradle.
   • In the Gradle JDK drop-down, select Download JDK and choose JDK 17.


2. Update Project Configuration

   Modify your build configuration to specify Java 17 as the target version. This involves updating the build.gradle file in your project.

   android {
       compileOptions {
           sourceCompatibility JavaVersion.VERSION_17
           targetCompatibility JavaVersion.VERSION_17
       }
       kotlinOptions {
           jvmTarget = "17"
       }
   }

   In your project-level build.gradle file, if you are using Kotlin, update the Kotlin version to 1.8.21 (or the latest available)

   buildscript {
       ext.kotlin_version = "1.8.21"
   }

   Update Android Gradle Plugin (AGP), in project-level build.gradle file, update the android build gradle dependency to:

   dependencies {
       classpath "com.android.tools.build:gradle:8.8.2"
   }

   In the gradle-wrapper.properties file, update the distributionUrl to:

   distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.2-bin.zip

3. Update Dependencies

   Ensure all dependencies are compatible with Java 17. Check for updates or replacements for any libraries that may not support Java 17.

4. Testing

   Thoroughly test your application to identify and resolve any issues that may arise from the migration. Use automated tests to ensure compatibility and stability.

5. Build and Deployment

   Update your build tools and CI/CD pipelines to use Java 17. Deploy the updated application to a staging environment for further testing before production rollout.

Benefits

• Improved performance and security.
• Access to new language features.
• Enhanced stability and efficiency.

2. Migration Guide from Android API Level 33 to API Level 35

Overview

Migrating from Android API Level 33 to API Level 35 involves updating your project to target the latest Android platform, ensuring compatibility with new features and optimizations.

Note: If you are targeting your application to Android API 35, it is mandatory to upgrade to Java 17. Google recommends using Java 17 as the minimum JDK version for targeting Android API 35. For more details, you can refer to the official documentation here.

Steps

1. Update Project Configuration

   Modify your build.gradle file to set compileSdkVersion and targetSdkVersion to 35:

   android {
   namespace("com.example.appname") // you need to add your package name here
       compileSdkVersion 35
       defaultConfig {
           targetSdkVersion 35
       }
   }

2. Update Dependencies

   Update all android and androidTest dependencies to their latest stable versions. Update the Kotlin version to 1.8.21 (or the latest available).

3. Edge-to-Edge Design Principles

   Implement edge-to-edge design principles to fully utilize the screen area. Refer to the Edge-to-Edge Design Guidelines for detailed instructions.

4. Testing            

   Test your application with the updated configurations in a staging environment to ensure compatibility and identify any potential issues early.

   Testing should include:

   • Staging Environment: Test your application with the updated configurations in a staging environment to ensure compatibility and identify any potential issues early.
                  
   • Device Coverage: Test on multiple devices ranging from the minimum API level supported by your application to API level 35. This ensures that your application works seamlessly across different Android versions and devices.
                  
   • Functional Testing: Verify that all functionalities of your application work as expected with the new configurations.
                  
   • Performance Testing: Assess the performance improvements brought by the new Android API level.
                  
   • Regression Testing: Ensure that existing features continue to work correctly after the migration.
              
          

Increased the minimal required API level

In order to support the new features and payment methods the minimal API level required for Mobile SDK has been changed to 24.

Please make sure your application uses minSdkVersion 24 or above.

Handling asynchronous payments with Ready-to-Use UI

To simplify the Ready-to-Use UI integration the CheckoutActivity will handle the redirect to the shopper result URL. For this reason the shopper result URL has been removed from the CheckoutSettings. As a result setting the intent filter for the shopper result URL and handling the redirect in onNewIntent callback are not required anymore.

API Deprecations

	Deprecated in 5.x.x	Use instead in 6.x.x
CheckoutThreeDS2Flow		Not used anymore.
CheckoutInfo
	String[] getThreeDS2Brands()	Not used anymore.
	CheckoutThreeDS2Flow getThreeDS2Flow()	Not used anymore.
	boolean isBrowserParamsRequired()	Not used anymore.

OPPThreeDSConfig *config = [[OPPThreeDSConfig alloc] init];
checkoutSettings.threeDSConfig = config;

let config = OPPThreeDSConfig()
checkoutSettings.threeDSConfig = config

Required dependencies

Because Mobile SDK distributed as .aar file it doesn't include transitive dependencies. Your application build.gradle must define them.

implementation "androidx.appcompat:appcompat:1.4.2"
implementation "androidx.recyclerview:recyclerview:1.2.1"
implementation "androidx.browser:browser:1.4.0"
implementation "androidx.fragment:fragment-ktx:1.4.1"
implementation "androidx.constraintlayout:constraintlayout:2.1.4"
implementation "androidx.webkit:webkit:1.6.0"
implementation "com.google.android.material:material:1.6.1"
implementation "com.google.code.gson:gson:2.8.9"

Make sure viewBinding feature is enabled.

buildFeatures {
    viewBinding true
}

Simplified 3D Secure 2.x integration

Since Mobile SDK 5.0.0 the external initialization of 3DS service was removed. Now it is fully managed by Mobile SDK. Please check 3D Secure 2 page for more details.

Using Activity Result API

The Mobile SDK started to use Activity Result API for Ready-to-Use UI. The method to create the intent was removed from CheckoutSettings, use CheckoutActivityResultContract instead. Please check Present Checkout UI for more details.

API Deprecations

	Deprecated in 4.x.x	Use instead in 5.x.x
CheckoutSettings
	Intent createCheckoutActivityIntent(Context context)	CheckoutActivityResultContract
	CheckoutSettings setProviderDomain(Connect.ProviderDomain providerDomain)	Not used anymore.
	Intent createCheckoutActivityIntent(Context context, ComponentName componentName)	CheckoutActivityResultContract
PaymentButtonFragment
	void submitTransaction(CheckoutSettings checkoutSettings, ComponentName componentName)	Set componentName in the CheckoutSettings before submitting transaction.
CardPaymentParams
	boolean isNumberValid(String cardNumber)	boolean isNumberValid(String cardNumber, boolean luhnCheck)
	boolean checkLuhn(String cardNumber)	boolean isNumberValid(String cardNumber, boolean luhnCheck)
OppPaymentProvider
	OppPaymentProvider(Context context, Connect.ProviderMode providerMode, Connect.ProviderDomain providerDomain)	Not used anymore.
	void requestPaymentBrandsForBin(String bin, String checkoutId, ITransactionListener listener)	void requestBinInfo(String checkoutId, String bin, BinInfoListener listener
	void sendThreeDS2AuthParams(String authParams, Transaction transaction, ThreeDS2AuthResponseListener listener)	The authentication parameters will be sent automatically.

Naming changes

com.oppwa.mobile.connect.threeds.OppThreeDSConfig -> com.oppwa.mobile.connect.provider.threeds.v2.model.ThreeDSConfig
com.oppwa.mobile.connect.threeds.constant.ChallengeUiType -> com.oppwa.mobile.connect.provider.threeds.v2.model.ChallengeUiType

ipworks3ds_sdk.xcframework // certified 3DS SDK

One framework instead of two

Mobile 3DS SDK wrapper oppwa.mobile.threeds.aar is deprecated now - all 3DS functionality is build into Mobile SDK oppwa.mobile.aar. So before moving forward remove oppwa.mobile.threeds.aar from your project.

Import mandatory library

As 3DS SDK now is a part of Mobile SDK you have to import the following framework to the project:

ipworks3ds_sdk.aar // certified 3DS SDK

Drag and drop ipworks3ds_sdk.aar (use ipworks3ds_sdk_deploy.aar for production) to the "libs" folder of the module where you plan to integrate Mobile SDK.

There are two versions of the ipworks3ds_sdk included: one to be used for development and one for production. The production version includes more strict security measures that would not allow for common development processes to occur, including running with attached debuggers or using simulators/emulators. The deployment version includes _deploy in the filename.