Link Android SDK

Learn how to integrate your app with the Link Android SDK

This guide covers the latest major version of the Link Android SDK, which is version 3.x. If you are using an older version of the SDK, consult the 1.x to 2.x and 2.x to 3.x migration guides.

Overview

The Plaid Link SDK is a quick and secure way to link bank accounts to Plaid in your Android app. Link is a drop-in module that handles connecting a financial institution to your app (credential validation, multi-factor authentication, error handling, etc). All without passing sensitive personal information to your server.

To get started with Plaid Link for Android, clone the GitHub repository and try out the example application, which provides a reference implementation in both Java and Kotlin. Youʼll want to sign up for free API keys through the Plaid Developer Dashboard to get started.

Examples of Plaid Link for Android

Requirements

A new version of the Android SDK will be released around the 15th of every month. You should keep your version up-to-date to provide the best Plaid Link experience in your application.

Update your project plugins

In your root-level (project-level) Gradle file (build.gradle), add rules to include the Android Gradle plugin. Check that you have Google's Maven repository as well.

1
2
3
4
5
6
7
8
9
10
11
buildscript {
repositories {
// Check that you have the following line (if not, add it):
google() // Google's Maven repository
mavenCentral() // Include to import Plaid Link Android SDK
jcenter() // Include to import Plaid Link transitive dependencies
}
dependencies {
// ...
}
}
Add the PlaidLink SDK to your app

In your module (app-level) Gradle file (usually app/build.gradle), add a line to the bottom of the file. The latest version of the PlaidLink SDK is Maven Central and can be found on Maven Central.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
android {
defaultConfig {
minSdkVersion 21 // or greater
}
// Enable Java 8 support for Link to work
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
dependencies {
// ...
implementation 'com.plaid.link:sdk-core:<insert latest version>'
}
Register your app ID

To register your Android app ID:

  1. Log into your Plaid Dashboard at the API page
  2. Next to Allowed Android Package Names click Configure then Add New Android Package Name
  3. Enter your package name, for example com.plaid.example
  4. Click Save Changes, you may be prompted to re-enter your password

Your Android app is now set up and ready to start integrating with the Plaid SDK.

Opening Link

Before you can open Link, you need to first create a link_token. A link_token can be configured for different Link flows and is used to control much of Link's behavior. To see how to create a new link_token, see the API Reference entry for /link/token/create. The /link/token/create call should include the android_package_name parameter.

Create a LinkTokenConfiguration

Each time you open Link, you will need to get a new link_token from your server and create a new LinkTokenConfiguration object with it.

1
2
3
val linkTokenConfiguration = linkTokenConfiguration {
token = "LINK_TOKEN_FROM_SERVER"
}
Create a PlaidHandler

Create a PlaidHandler - A PlaidHandler is a one-time use object used to open a Link session. It should be created as early as possible to warm-up Link so that it opens quickly. We recommend doing this as early as possible, since it must be completed before Link opens, and if delayed until just before Link opening it can have a perceptible impact on Link startup time.

1
val plaidHandler: PlaidHandler = Plaid.create(application, linkTokenConfiguration)
Open Link

Finally, open Link by calling open on the PlaidHandler object in an Activity or Fragment. This will usually be done in a button's onClick function.

Note The Activity or Fragment passed in the open function will be used to return the result.

1
plaidHandler.open(activity)

Handling Results

The Link SDK uses the standard Android startActivityForResult and onActivityResult APIs to show Link and return the result to your application.

Create a LinkResultHandler

First create a LinkResultHandler to parse the result out of the returned intent.

1
2
3
4
private val linkResultHandler = LinkResultHandler(
onSuccess = { it: LinkSuccess -> /* handle onSuccess */ },
onExit = { it: LinkExit -> /* handle onExit */ }
)
Parse the Result in onActivityResult

Call the onActivityResult function of LinkResultHandler to parse the result. This function will return true if the result if the result was sent from Link and was parsed by the handler.

1
2
3
4
5
6
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (!linkResultHandler.onActivityResult(requestCode, resultCode, data)) {
Log.i(MainActivity::class.java.simpleName, "Not handled by the LinkResultHandler");
}
}

onSuccess

The method is called when a user has successfully onboarded their account. The onSuccess handler returns a LinkConnection class that includes the public_token, and additional Link metadata in the form of a LinkConnectionMetadata class.

onSuccess
publicTokenString
Displayed once a user has successfully linked their Item.
metadataObject
Displayed once a user has successfully linked their Item.
accountsList<LinkAccount>
A list of accounts attached to the connected Item. If Select Account is enabled via the developer dashboard, accounts will only include selected accounts.
idstring
The Plaid account_id
namestring
The official account name
maskstring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, it may also not match the mask that the bank displays to the user.
subtypeLinkAccountSubtype
The account subtype. See the Account schema for a full list of possible values
typeLinkAccountType
The account type. See the Account schema for a full list of possible values
verification_statusstring
When micro-deposit-based verification is being used, the accounts object includes an Item's verification_status. Possible values are:
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the two amounts.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.
institutionobject
An institution object
namestring
The full institution name, such as 'Wells Fargo'
institution_idstring
The Plaid institution identifier
linkSessionIdString
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
metadataJsonMap
The data directly returned from the server with no client side changes.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
private val linkResultHandler = LinkResultHandler(
// ...
onSuccess = { it: LinkSuccess ->
// Send public_token to your server, exchange for access_token
val publicToken = it.publicToken
val metadata = it.metadata
metadata.accounts.forEach { account ->
val accountId = account.id
val accountName = account.name
val accountMask = account.mask
val accountSubType = account.subtype
}
val institutionId = metadata.institution?.id
val institutionName = metadata.institution?.name
}
)

onExit

The onExit handler is called when a user exits the Link flow prematurely or when an error occurs during Link initialization. The PlaidError returned from the onExit handler is meant to help you guide your users after they have exited Link. We recommend storing the error and metadata information server-side in a way that can be associated with the user. You’ll also need to include this and any other relevant info in Plaid Support requests for the user.

onExit
errorMap<String, Object>
An object that contains the error type, error code, and error message of the error that was last encountered by the user. If no error was encountered, error will be null.
displayMessageString
A user-friendly representation of the error code. null if the error is not related to user action. This may change over time and is not safe for programmatic use.
errorCodeString
The particular error code. Each errorType has a specific set of errorCodes. A code of 499 indicates a client-side exception.
jsonString
A string representation of the error code.
errorTypeString
A broad categorization of the error.
errorMessageString
A developer-friendly representation of the error code.
errorJsonString
The data directly returned from the server with no client side changes.
LinkExitMetadataMap<String, Object>
An object containing information about the exit event
linkSessionIdString
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
institutionobject
An institution object
namestring
The full institution name, such as 'Wells Fargo'
institution_idstring
The Plaid institution identifier
statusString
The point at which the user exited the Link flow. One of the following values.
requires_questions
User prompted to answer security questions
requires_selections
User prompted to answer multiple choice question(s)
requires_recaptcha
User prompted to solve a ReCAPTCHA challenge
requires_code
User prompted to provide a one-time passcode
choose_device
User prompted to select a device on which to receive a one-time passcode
requires_credentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution
institution_not_found
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
unknown
An exit status that is not handled by the current version of the SDK
requestIdString
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
private val linkResultHandler = LinkResultHandler(
// ...
onExit = {
val error = it.error
error?.let { err ->
val errorCode = err.errorCode
val errorMessage = err.errorMessage
val displayMessage = err.displayMessage
}
val metadata = it.metadata
val institutionId = metadata.institution?.id
val institutionName = metadata.institution?.name
val linkSessionId = metadata.linkSessionId;
val requestId = metadata.requestId;
}
)

onEvent

The onEvent callback is called at certain points in the Link flow. Unlike the handlers for onSuccess, onExit, and onCancelled, the onEvent handler is initialized as a global lambda passed to the Plaid class. OPEN events will be sent immediately upon Link’s opening, and remaining events will be sent by the time onSuccess or onExit is called. If you need the exact time when an event happened, use the timestamp property.'
The following onEvent callbacks are stable, which means that they will not be deprecated or changed: OPEN, EXIT, HANDOFF, SELECT_INSTITUTION, ERROR. The remaining callback events are informational and subject to change, and therefore should not be used to customize your product experience.

onEvent
eventNameString
A string representing the event that has just occurred in the Link flow.
CLOSE_OAUTH
The user closed the third-party website or mobile app without completing the OAuth flow.
ERROR
A recoverable error occurred in the Link flow, see the error_code metadata.
EXIT
The user has exited without completing the Link flow and the onExit callback is fired.
FAIL_OAUTH
The user encountered an error while completing the third-party's OAuth login flow.
HANDOFF
The user has completed the Link flow and the onSuccess callback is fired.
OPEN
The user has opened Link.
OPEN_MY_PLAID
The user has opened my.plaid.com. This event is only sent when Link is initialized with assets as a product.
OPEN_OAUTH
The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.
MATCHED_SELECT_INSTITUTION
The user selected an institution that was presented as a matched institution.
MATCHED_SELECT_VERIFY_METHOD
The user selected a verification method for a matched institution.
SEARCH_INSTITUTION
The user has searched for an institution.
SELECT_BRAND
The user selected a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.
SELECT_INSTITUTION
The user selected an institution.
SUBMIT_CREDENTIALS
The user has submitted credentials.
SUBMIT_MFA
The user has submitted MFA.
TRANSITION_VIEW
The TRANSITION_VIEW event indicates that the user has moved from one view to the next.
UNNOWN
The UNKNOWN event indicates that the event is not handled by the current version of the SDK.
LinkEventMetadataMap<String, Object>
An object containing information about the event.
errorCodeString
The error code that the user encountered. Emitted by: ERROR, EXIT.
errorMessageString
The error message that the user encountered. Emitted by: ERROR, EXIT.
errorTypeString
The error type that the user encountered. Emitted by: ERROR, EXIT.
exitStatusString
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT.
institutionIdString
The ID of the selected institution. Emitted by: all events.
institutionNameString
The name of the selected institution. Emitted by: all events.
institutionSearchQueryString
The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
linkSessionIdString
The link_session_id is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: all events.
mfaTypeString
If set, the user has encountered one of the following MFA types: code device questions selections. Emitted by: SUBMIT_MFA and TRANSITION_VIEW when view_name is MFA.
requestIdString
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
selectionString
The verification method for a matched institution selected by the user. Possible values are phoneotp, password. Emitted by: MATCHED_SELECT_VERIFY_METHOD.
timestampString
An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.
viewNameString
The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.
CONNECTED
The user has connected their account.
CONSENT
We ask the user to consent to the privacy policy.
CREDENTIAL
Asking the user for their account credentials.
ERROR
An error has occurred.
EXIT
Confirming if the user wishes to close Link.
LOADING
Link is making a request to our servers.
MATCHED_CONSENT
We ask the matched user to consent to the privacy policy and SMS terms.
MATCHED_CREDENTIAL
We ask the matched user for their account credentials to a matched institution.
MATCHED_MFA
We ask the matched user for MFA authentication to verify their identity.
MFA
The user is asked by the institution for additional MFA authentication.
NUMBERS
The user is asked to insert their account and routing numbers.
RECAPTCHA
The user was presented with a Google reCAPTCHA to verify they are human.
SELECT_ACCOUNT
We ask the user to choose an account.
SELECT_BRAND
The user selected a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.
SELECT_INSTITUTION
We ask the user to choose their institution.
metadataJsonString
The data directly returned from the server with no client side changes.
1
Plaid.setLinkEventListener { event -> Log.i("Event", event.toString()) }

OAuth

Using Plaid Link with an OAuth flow requires some additional setup instructions. For details, see the OAuth Guide.

Troubleshooting

Pass a LinkLogLevel value with the LinkTokenConfiguration to get visible logs. From least to most verbose: ERROR, WARN, INFO, DEBUG, VERBOSE.

1
2
3
4
val linkTokenConfiguration = linkTokenConfiguration {
token = "LINK_TOKEN_FROM_SERVER"
logLevel = if (BuildConfig.DEBUG) LinkLogLevel.VERBOSE else LinkLogLevel.ERROR
}

Upgrading

Please see our GitHub repository for version release notes. Steps to upgrade to the latest version can be found at 2.x to 3.x.