Plaid logo
Docs
ALL DOCS

Link

  • Overview
Libraries
  • Web
  • iOS
  • Android
  • React Native
  • Webview
Core Link flows
  • OAuth guide
  • Update mode
  • Preventing duplicate Items
  • Data Transparency Messaging migration
  • Account Select v2 migration guide
  • Link Token migration guide
  • Legacy public key integrations
Optimizing Link
  • Optimizing Link conversion
  • Measuring Link conversion
  • Pre-Link messaging
  • Customizing Link
  • Choosing when to inititalize products
  • Returning user experience
  • Modular Link (UK/EU only)
Errors and troubleshooting
  • Troubleshooting
  • Handling an invalid Link Token
  • Institution status in Link
Plaid logo
Docs
Plaid.com
Get API keys
Open nav

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 migration guide.

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), 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

Prefer to learn by watching? A video guide is available for this content.

Initial Android setup

Before writing code using the SDK, you must first perform some setup steps to register your app with Plaid and configure your project.

Register your app ID

To register your Android app ID:

  1. Sign in to the Plaid Dashboard and go to the Team Settings -> 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.

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

New versions of the Android SDK are released frequently, at least once every few months. 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.

Copy
1buildscript {
2 repositories {
3 // Check that you have the following line (if not, add it):
4 google() // Google's Maven repository
5 mavenCentral() // Include to import Plaid Link Android SDK
6 }
7 dependencies {
8 // ...
9 }
10}
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.

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

If your app uses Identity Verification, a user may need to take a picture of identity documentation or a selfie during the Link flow. To support this workflow, the CAMERA , WRITE_EXTERNAL_STORAGE, RECORD_AUDIO, and MODIFY_AUDIO_SETTINGS permissions need to be added to your application's AndroidManifest.xml. (While Plaid does not record any audio, some older Android devices require these last two permissions to use the camera.) The WRITE_EXTERNAL_STORAGE permission should be limited to < Android 9 (i.e. maxSdk=28). If these permissions are not granted in an app that uses Identity Verification, the app may crash during Link.

Opening Link

Before you can open Link, you need to first create a link_token by calling /link/token/create from your backend. This call should never happen directly from the mobile client, as it risks exposing your API secret. The /link/token/create call must include the android_package_name parameter, which should match the applicationId from your app-level build.gradle file. You can learn more about applicationId in Google's Android developer documentation.

Select group for content switcher
Select Language
Copy
1const request: LinkTokenCreateRequest = {
2 user: {
3 client_user_id: 'user-id',
4 },
5 client_name: 'Plaid Test App',
6 products: ['auth', 'transactions'],
7 country_codes: ['GB'],
8 language: 'en',
9 webhook: 'https://sample-web-hook.com',
10 android_package_name: 'com.plaid.example'
11 },
12};
13try {
14 const response = await plaidClient.linkTokenCreate(request);
15 const linkToken = response.data.link_token;
16} catch (error) {
17 // handle error
18}
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.

Select Language
Copy
1val linkTokenConfiguration = linkTokenConfiguration {
2 token = "LINK_TOKEN_FROM_SERVER"
3}

The Link SDK runs as a separate Activity within your app. In order to return the result to your app, it supports both the standard startActivityForResult and onActivityResult and the ActivityResultContract result APIs.

Select group for content switcher
Register a callback for an Activity Result
Select Language
Copy
1private val linkAccountToPlaid =
2registerForActivityResult(OpenPlaidLink()) {
3 when (it) {
4 is LinkSuccess -> /* handle LinkSuccess */
5 is LinkExit -> /* handle LinkExit */
6 }
7}
Open Link
Select Language
Copy
1linkAccountToPlaid.launch(linkTokenConfiguration)

At this point, Link will open, and will trigger the onSuccess callback if the user successfully completes the Link flow.

onSuccess

The method is called when a user successfully links an Item. The onSuccess handler returns a LinkConnection class that includes the public_token, and additional Link metadata in the form of a LinkConnectionMetadata class.

onSuccess
publicToken
String
Displayed once a user has successfully linked their Item.
metadata
Object
Displayed once a user has successfully linked their Item.
accounts
List<LinkAccount>
A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, accounts will only include selected accounts.
id
string
The Plaid account_id
name
string
The official account name
mask
nullable string
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.
subtype
LinkAccountSubtype
The account subtype. See the Account schema for a full list of possible values
type
LinkAccountType
The account type. See the Account schema for a full list of possible values
verification_status
nullable string
The accounts object includes an Item's micro-deposit 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.
null: The Item is not using micro-deposit verification.
institution
nullable object
An institution object. If the Item was created via Same-Day micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
institution_id
string
The Plaid institution identifier
linkSessionId
nullable String
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.
metadataJson
nullable Map
The data directly returned from the server with no client side changes.
Select Language
Copy
1val success = result as LinkSuccess
2
3// Send public_token to your server, exchange for access_token
4val publicToken = success.publicToken
5val metadata = success.metadata
6metadata.accounts.forEach { account ->
7 val accountId = account.id
8 val accountName = account.name
9 val accountMask = account.mask
10 val accountSubType = account.subtype
11}
12val institutionId = metadata.institution?.id
13val institutionName = metadata.institution?.name

onExit

The onExit handler is called when a user exits Link without successfully linking an Item, 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 information in Plaid Support requests for the user.

onExit
error
Map<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.
displayMessage
nullable String
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.
errorCode
String
The particular error code. Each errorType has a specific set of errorCodes. A code of 499 indicates a client-side exception.
json
String
A string representation of the error code.
errorType
String
A broad categorization of the error.
errorMessage
String
A developer-friendly representation of the error code.
errorJson
nullable String
The data directly returned from the server with no client side changes.
LinkExitMetadata
Map<String, Object>
An object containing information about the exit event
linkSessionId
nullable String
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.
institution
nullable object
An institution object. If the Item was created via Same-Day micro-deposit verification, will be null.
name
string
The full institution name, such as 'Wells Fargo'
institution_id
string
The Plaid institution identifier
status
nullable String
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
requires_account_selection
User prompted to select one or more financial accounts to share
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
requestId
nullable String
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation
Select Language
Copy
1val exit = result as LinkExit
2
3val error = exit.error
4error?.let { err ->
5 val errorCode = err.errorCode
6 val errorMessage = err.errorMessage
7 val displayMessage = err.displayMessage
8}
9val metadata = exit.metadata
10val institutionId = metadata.institution?.id
11val institutionName = metadata.institution?.name
12val linkSessionId = metadata.linkSessionId;
13val requestId = metadata.requestId;

onEvent

The onEvent callback is called at certain points in the Link flow. Unlike the handlers for onSuccess and onExit, 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, BANK_INCOME_INSIGHTS_COMPLETED. The remaining callback events are informational and subject to change.

onEvent
eventName
String
A string representing the event that has just occurred in the Link flow.
BANK_INCOME_INSIGHTS_COMPLETED
The user has completed the Assets and Bank Income Insights 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 exited Link after successfully linking an Item.
IDENTITY_VERIFICATION_START_STEP
The user has started a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_PASS_STEP
The user has passed a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_FAIL_STEP
The user has failed a step of the Identity Verification flow. The step is indicated by view_name.
IDENTITY_VERIFICATION_PENDING_REVIEW_STEP
The user has reached the pending review state.
IDENTITY_VERIFICATION_CREATE_SESSION
The user has started a new Identity Verification session.
IDENTITY_VERIFICATION_RESUME_SESSION
The user has resumed an existing Identity Verification session.
IDENTITY_VERIFICATION_PASS_SESSION
The user has successfully completed their Identity Verification session.
IDENTITY_VERIFICATION_FAIL_SESSION
The user has failed their Identity Verification session.
IDENTITY_VERIFICATION_OPEN_UI
The user has opened the UI of their Identity Verification session.
IDENTITY_VERIFICATION_RESUME_UI
The user has resumed the UI of their Identity Verification session.
IDENTITY_VERIFICATION_CLOSE_UI
The user has closed the UI of their Identity Verification session.
MATCHED_SELECT_INSTITUTION
The user selected an institution that was presented as a matched institution. This event can be emitted either during the Returning User Experience flow or if the institution's routing_number was provided when calling /link/token/create. To distinguish between the two scenarios, see LinkEventMetadata.match_reason.
MATCHED_SELECT_VERIFY_METHOD
The user selected a verification method for a matched institution. This event is emitted only during the Returning User Experience flow.
OPEN
The user has opened Link.
OPEN_MY_PLAID
The user has opened my.plaid.com. This event is only emitted 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.
SEARCH_INSTITUTION
The user has searched for an institution.
SELECT_BRAND
The user selected a brand, e.g. Bank of America. The SELECT_BRAND event is only emitted for large financial institutions with multiple online banking portals.
SELECT_DEGRADED_INSTITUTION
The user selected an institution with a DEGRADED health status and were shown a corresponding message.
SELECT_DOWN_INSTITUTION
The user selected an institution with a DOWN health status and were shown a corresponding message.
SELECT_INSTITUTION
The user selected an institution.
SUBMIT_ACCOUNT_NUMBER
The user has submitted an account number. This event emits the account_number_mask metadata to indicate the mask of the account number the user provided.
SUBMIT_CREDENTIALS
The user has submitted credentials.
SUBMIT_MFA
The user has submitted MFA.
SUBMIT_ROUTING_NUMBER
The user has submitted routing number. This event emits the routing_number metadata to indicate user's routing number.
TRANSITION_VIEW
The TRANSITION_VIEW event indicates that the user has moved from one view to the next.
UPLOAD_DOCUMENTS
The user is asked to upload documents (for Income verification).
VIEW_DATA_TYPES
The user has viewed data types on the data transparency consent pane.
UNKNOWN
The UNKNOWN event indicates that the event is not handled by the current version of the SDK.
LinkEventMetadata
Map<String, Object>
An object containing information about the event.
accountNumberMask
String
The account number mask extracted from the user-provided account number. If the user-inputted account number is four digits long, account_number_mask is empty. Emitted by SUBMIT_ACCOUNT_NUMBER.
errorCode
String
The error code that the user encountered. Emitted by: ERROR, EXIT.
errorMessage
String
The error message that the user encountered. Emitted by: ERROR, EXIT.
errorType
String
The error type that the user encountered. Emitted by: ERROR, EXIT.
exitStatus
String
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT.
institutionId
String
The ID of the selected institution. Emitted by: all events.
institutionName
String
The name of the selected institution. Emitted by: all events.
institutionSearchQuery
String
The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
matchReason
nullable string
The reason this institution was matched, which will be either returning_user or routing_number. Emitted by: MATCHED_SELECT_INSTITUTION.
routingNumber
Optional<String>
The routing number submitted by user at the micro-deposits routing number pane. Emitted by SUBMIT_ROUTING_NUMBER.
linkSessionId
String
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.
mfaType
String
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.
requestId
String
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
selection
String
Either the verification method for a matched institution selected by the user or the Auth Type Select flow type selected by the user. If selection is used to describe selected verification method, then possible values are phoneotp or password; if selection is used to describe the selected Auth Type Select flow, then possible values are flow_type_manual or flow_type_instant. Emitted by: MATCHED_SELECT_VERIFY_METHOD and SELECT_AUTH_TYPE.
timestamp
String
An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.
viewName
String
The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.
ACCEPT_TOS
The view showing Terms of Service in the identity verification flow.
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.
DATA_TRANSPARENCY
We disclose the data types being shared.
DATA_TRANSPARENCY_CONSENT
We ask the user to consent to the privacy policy and disclose data types being shared.
DOCUMENTARY_VERIFICATION
The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).
ERROR
An error has occurred.
EXIT
Confirming if the user wishes to close Link.
KYC_CHECK
The view representing the "know your customer" step in the identity verification flow.
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.
OAUTH
The user is informed they will authenticate with the financial institution via OAuth.
RECAPTCHA
The user was presented with a Google reCAPTCHA to verify they are human.
RISK_CHECK
The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).
SCREENING
The watchlist screening step in the identity verification flow.
SELECT_ACCOUNT
We ask the user to choose an account.
SELECT_AUTH_TYPE
The user is asked to choose whether to Link instantly or manually (i.e., with micro-deposits).
SELECT_BRAND
The user is asked to select 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.
SELFIE_CHECK
The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.
UPLOAD_DOCUMENTS
The user is asked to upload documents (for Income verification).
VERIFY_SMS
The SMS verification step in the identity verification flow.
metadataJson
nullable String
The data directly returned from the server with no client side changes.
Select Language
Copy
1Plaid.setLinkEventListener { event -> Log.i("Event", event.toString()) }

Next steps

If you run into problems integrating with Plaid Link on Android, see Troubleshooting the Plaid Link Android SDK.

Once you've gotten Link working, see Link best practices for recommendations on further improving the Link flow.

Was this helpful?
Developer community
GitHub
GitHub
Stack Overflow
Stack Overflow
YouTube
YouTube
Twitter
Twitter
Discord
Discord