# Using the Mastercard Data Connect Android SDK source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/android-sdk/index.md The Mastercard Data Connect Android SDK is distributed as a compiled binary in Maven Central which allows you to easily integrate our SDK into your development projects. Maven central is Android's officially supported format for distributing binary libraries to multiple platforms and architectures in a single bundle. Note: Chase bank (JPMorgan Chase) has removed support for certain types of WebView traffic. This will impact the Chase OAuth flow if your SDK integration is not using the most recent version of our SDKs. The latest version will support secure web containers, e.g., Custom Tabs. For more information see the [Chase Developer documentation](https://developer.chase.com/products/aggregation-consent/guides/launching-the-oauth-flow-in-a-secure-container/) Warning: The Data Connect Android SDK does not support the Connect Transfer flow (for Deposit Switch and Bill Pay Switch). We provide a separate Connect Transfer Android SDK for this purpose. See the [Deposit Switch and Bill Pay Switch documentation](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/index.md) for details. ## Compatibility {#compatibility} * Android 5.0 (Lollipop) or later, Android SDK level 21 or later: Warning: Support for deepLinkUrl parameters is deprecated from version 3.0.0 of the Data Connect Android SDK. Going forward you should use the `redirectUrl` parameter, which supports both universal and deep links. See our [Github changelog entry](https://github.com/Mastercard/connect-android-sdk/blob/main/CHANGELOG.md#300-august-10-2023). * Android 15 or later, Android SDK level 35 or later: Note: Starting from version 3.0.6, the Data Connect Android SDK will handle the redirect internally via a fallback mechanism if you do not specify a `redirectUrl` via the SDK or a `redirectUri` from [Generate Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) (this fixes a problem seen on Android 15+ where the OAuth popup might not dismiss automatically). See our [Github changelog entry](https://github.com/Mastercard/connect-android-sdk/blob/main/CHANGELOG.md#306-october-7-2025). For best results, we recommend you specify an app link via `redirectUrl` as described in the [App to App Support](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/android-sdk/index.md#app-to-app-support) section or use a `redirectUri`. Otherwise, you should update your code to use version 3.0.6 or later of the SDK. ## Install the Data Connect Android SDK {#install-the-data-connect-android-sdk} Install the Data Connect Android SDK using Maven Central or manually from GitHub. ### Maven Central {#maven-central} Modify your root-level Gradle file (`build.gradle`) as follows: ```gradle allprojects { repositories { google() mavenCentral() } } ``` Modify your app-level Gradle file (`build.gradle`) as follows: ```html android { defaultConfig { minSdkVersion 21 // or greater } } dependencies { // ... implementation 'com.mastercard.openbanking.connect:connect-sdk:' } ``` **Note** : The latest version of the Data Connect Android SDK can be found in [Maven Central](https://central.sonatype.com/artifact/com.mastercard.openbanking.connect/connect-sdk/2.3.0/versions). ### Manual Install {#manual-install} Import the `connect-sdk` module into your project as follows: 1. Clone the Data Connect Android SDK from [Github](https://github.com/Mastercard/connect-android-sdk) 2. On your Android project, click on **File** \> **New** \> **Import Module** , select the folder you cloned the Data Connect Android SDK into, then click **Finish**. 3. Modify the [build.gradle](https://github.com/Mastercard/connect-android-sdk/blob/main/connect-sdk/build.gradle) file in the `connect-sdk` module to remove the following lines: apply from: "$project.rootDir/sonar.gradle" apply from: "${rootProject.projectDir}/sonatype-publish.gradle" 4. Clean and build the project. ## Update Android application settings {#update-android-application-settings} The Data Connect Android SDK requires internet access to connect with our servers, so you need to add internet permissions to the `AndroidManifest.xml` file: ```xml ``` #### App Link Support {#app-link-support} Add the following activity to the **AndroidManifest.xml** file. Tip: In order to have the best app to app authentication experience, you should use an App link URL in the `redirectUrl` parameter shown in example below. We do not recommend using deep links (custom URL schemes). ```html ``` #### Deep Link Support {#deep-link-support} Add the following activity to the **AndroidManifest.xml** file. ```html ``` Note: `{deep_link_app_name}` is case sensitive and should only use lower-case characters. ## Add code to start the Data Connect Android SDK {#add-code-to-start-the-data-connect-android-sdk} ### Data Connect Class {#data-connect-class} The Data Connect class contains a start method that when called, starts an activity with the supplied event listener. The SDK only allows a single instance of the Data Connect activity to run. If you start Data Connect while a Data Connect activity is already running, a RuntimeException is thrown. The Data Connect Android SDK's main component is the Data Connect class that contains a static start method, which runs an activity that connects with the EventHandler. To access the APIs in the SDK include the following imports: ```Java import com.mastercard.openbanking.connect.Connect; import com.mastercard.openbanking.connect.EventHandler; ``` **App Link Support** ```Java Connect.start(this, url, "https://example.com/connect", eventHandler); ``` **Deep Link Support** ```Java Connect.start(this, url, "{deep_link_app_name}://", eventHandler); ``` * Java * Kotlin ```java public static void start(Context context, String connectUrl, String redirectUrl, EventHandler eventHandler) ``` ```kotlin fun start(context: Context, connectUrl: String?, redirectUrl: String?, eventHandler: EventHandler?) ``` #### Parameters {#parameters} | Parameter | Description | |-------------------------|----------------------------------------------------------------------------------------------------------------------------------------| | context (required) | The Android Context is referenced by Data Connect when an activity starts. | | connectUrl (required) | The SDK loads the Data Connect URL. | | redirectUrl (optional) | App Links URL to redirect back to your mobile app after completing an FI's OAuth flow. This parameter is only required for App to App. | | eventHandler (required) | A class implementing the EventHandler interface. | ### EventHandler Interface {#eventhandler-interface} Throughout Data Connect's flow, events about the state of the web application are sent as JSONObjects to the EventHandler methods. The onUserEvent handler will not return anything unless you're specifically targeting Data Connect. * Java * Kotlin ```java public interface EventHandler { void onLoaded(); void onDone(JSONObject doneEvent); void onCancel(JSONObject cancelEvent); void onError(JSONObject errorEvent); void onRouteEvent(JSONObject routeEvent); void onUserEvent(JSONObject userEvent); } ``` ```kotlin interface EventHandler { fun onLoaded() fun onDone(doneEvent: JSONObject?) fun onCancel(cancelEvent JSONObject?) fun onError(errorEvent: JSONObject?) fun onRouteEvent(routeEvent: JSONObject?) fun onUserEvent(userEvent: JSONObject?) } ``` #### Callback Events {#callback-events} See [here](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md#callback-events) for details on the events via their callback interface. **Note** : The onDone, onError, onRoute, and onUser callback functions will have a **JSONObject** parameter that contains data about the event. ## App to App Support {#app-to-app-support} To provide the best app to app authentication experience for your customers, you should send an App link in the `redirectUrl` parameter when using Data Connect. See [App To App Authentication](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md#app-to-app-authentication) for more details, including [how to test](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md#how-to-test-app-to-app-authentication). Before installing the Data Connect Android SDK for use with app to app authentication, complete the following: * Create your domain's `redirectUrl` (App link) * Configure your `redirectUrl` Note: Starting from version 3.0.6, the Data Connect Android SDK will handle the redirect internally via a fallback mechanism if you do not specify a `redirectUrl` via the SDK or a `redirectUri` from [Generate Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) (this fixes a problem seen on Android 15+ where the OAuth popup might not dismiss automatically). See our [Github changelog entry](https://github.com/Mastercard/connect-android-sdk/blob/main/CHANGELOG.md#306-october-7-2025). For best results, we recommend you specify an app link via `redirectUrl` as described in this section or use a `redirectUri`. Otherwise, you should update your code to use version 3.0.6 or later of the SDK. ### Create your domain's redirectUrl {#create-your-domains-redirecturl} For information on how to create a [App Links](https://developer.android.com/training/app-links#android-app-links) as redirectUrl in your application, see [adding Android App Links](https://developer.android.com/studio/write/app-link-indexing) for details. Tip: In order to provide the best app to app authentication customer experience, you should use an app link for `redirectUrl`. We do not recommend using a deep link (custom URL scheme) for `redirectUrl` since deep links lack the security of App Links through the two-way association between your app and your website. Any application can register custom URL schemes and there is no further validation from Android. If multiple applications have registered the same custom URL scheme, a different application may be launched each time the URL is opened. To complete OAuth flows, it is important that your application is opened and not any arbitrary application that has registered the same URL scheme. ### Configuring your redirectUrl {#configuring-your-redirecturl} The `redirectUrl` URL is used to redirect back to your mobile app after completing the FI's OAuth flow (this should be an app link). Here is an example of an app link redirectUrl within your code: Connect.start(this, url, "https://example.com/mastercardConnect", eventHandler); For information on how to configure your server to support App Links see [Verify Android App Links](https://developer.android.com/training/app-links/verify-android-applinks#web-assoc) in the Android documentation. ### Manually Stop a Data Connect Activity {#manually-stop-a-data-connect-activity} The Data Connect activity will automatically finish on done, cancel, and error events. You can manually finish a Data Connect activity by invoking: ```java Connect.finishCurrentActivity() ``` If there isn't a current Data Connect activity running, then the method will throw a RuntimeException.