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

Maintaining a public-key based integration

Details and guidance on maintaining a legacy public_key based Link integration for older Plaid API versions.

Overview

In July 2020, Plaid introduced the link_token, which replaces the static public_key. While integrations using the public_key are still supported, it is recommended that you upgrade your integration to use a link_token instead, as future Plaid development and features will be based on the link_token infrastructure. To start upgrading, see the Link token migration guide.

Plaid Link for Web

This section provides instructions for maintaining Plaid integrations using the deprecated public_key parameter. These instructions cannot be used for new integrations or for adding OAuth support to existing integrations. For up-to-date content on this topic, see the Link Web SDK instead. For instructions on updating an existing legacy integration, see the Link token migration guide.

Installation

Include the Plaid Link initialize script on each page of your site. It should always be loaded directly from https://cdn.plaid.com, rather than included in a bundle or hosted yourself.

Copy
1<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>

Create

Plaid.create accepts one argument, a configuration Object, and returns an Object with two functions, open and exit. Calling open will display the Consent Pane view, and calling exit will close Link. Note: Control whether or not your Link integration uses the Account Select view from the Dashboard.

create_legacy
clientName
string
Displayed once a user has successfully linked their Item.
env
string
The Plaid API environment on which to create user accounts. Possible values are development, sandbox, respectively. For Production use, use production.
key
string
The public_key associated with your account; available from the Dashboard.
product
string
A list of Plaid products you wish to use. Valid products are: transactions, auth, identity, assets, investments, liabilities, and payment_initiation. Example: ['auth', 'transactions']. balance is not a valid value, the Balance product does not require explicit initalization and will automatically be initialized when any other product is initialized. Only institutions that support all requested products will be shown in Link.
In Production, you will be billed for each product that you specify when initializing Link. Note that a product cannot be removed from an Item once the Item has been initialized with that product. To stop billing on an Item for subscription-based products, such as Liabilities, Investments, and Transactions, remove the Item via /item/remove.
onSuccess
callback
A function that is called when a user successfully links an Item. The function should expect two arguments, the public_token and a metadata object. See onSuccess.
onExit
callback
A function that is called when a user has specifically exited the Link flow or if Link failed to initialize. The function should expect two arguments, a nullable error object and a metadata object. See onExit.
onEvent
callback
A function that is called when a user reaches certain points in the Link flow. The function should expect two arguments, an eventName string and a metadata object.
onLoad
callback
A function that is called when the Link module has finished loading. Calls to plaidLinkHandler.open() prior to the onLoad callback will be delayed until the module is fully loaded.
language
string
Specify a Plaid-supported language to localize Link. English will be used by default. Supported languages:
  • English ('en')
  • French ('fr')
  • Spanish ('es')
  • Dutch ('nl')
When using a Link customization, language must be set to match the language used in the customization.
countryCodes
string
Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard. Note that if you initialize with a European country code, your users will see the European consent panel during the Link flow. Supported country codes are: US, CA, ES, FR, GB, IE, NL. If not specified, will default to ['US']. If Link is launched with multiple countryCodes, only products that you are enabled for in all countries will be used by Link.
If a Link customization is being used, the countries configured here should match those in the customization.
To use the Auth features Instant Match, Automated Micro-deposits, or Same-day Micro-deposits, countryCodes must be set to ['US'].
accountSubtypes
object
By default, Link will only display account types that are compatible with all products supplied in the product parameter. You can further limit the accounts shown in Link by using accountSubtypes to specify the account subtypes to be shown in Link. Only the specified subtypes will be shown. To indicate that all subtypes should be shown, use the value "all". If the accountSubtypes filter is used, any account type for which a filter is not specified will be entirely omitted from Link.
Example value:
{
"depository": ["checking", "savings"],
"credit": ["all"]
}
For a full list of valid types and subtypes, see the Account schema.
For institutions using OAuth, the filter will not affect the list of institutions shown by the bank in the OAuth window.
<accountType>: [accountSubtype]
string
An object of accountTypes composed of an array of accountSubtypes to filter.
webhook
string
Specify a webhook to associate with an Item. Plaid fires a webhook when the Item requires updated credentials, when new data is available, or when Auth numbers have been successfully verified.
token
string
Specify a public_token to launch Link in update mode for a particular Item. This will cause Link to open directly to the authentication step for that Item's institution. Use the /item/public_token/create endpoint to generate a public_token for an Item.
linkCustomizationName
string
Specify the name of a Link customization created in the Dashboard. The default customization is used if none is provided. When using a Link customization, the language in the customization must match the language configured via the language parameter.
oauthNonce
string
An oauthNonce is required to support OAuth authentication flows when launching or re-launching Link on a mobile device and using one or more European country codes. The nonce must be at least 16 characters long.
oauthRedirectUri
string
An oauthRedirectUri is required to support OAuth authentication flows when launching Link on a mobile device. Note that any redirect URI must also be added to the Allowed redirect URIs list in the developer dashboard.
oauthStateId
string
An oauthStateId is required to support OAuth authentication flows when re-launching Link on a mobile device.
paymentToken
string
A paymentToken must be specified if you are using the Payment Initiation (UK and Europe) product. This will cause Link to open directly to the Payment Initiation flow. Use the /payment_initiation/payment/token/create endpoint to generate a payment_token.
userLegalName
string
The end user's legal name
userPhoneNumber
string
The end user's phone number
userEmailAddress
string
The end user's email address
Copy
1const handler = Plaid.create({
2 clientName: 'Plaid Quickstart',
3 env: 'sandbox',
4 key: 'PUBLIC_KEY',
5 product: ['transactions'],
6 onSuccess: (public_token, metadata) => {},
7 onLoad: () => {},
8 onExit: (err, metadata) => {},
9 onEvent: (eventName, metadata) => {},
10 countryCodes: ['US'],
11 webhook: 'https://requestb.in',
12 linkCustomizationName: '',
13 language: 'en',
14 oauthNonce: null,
15 oauthRedirectUri: null,
16 oauthStateId: null,
17 token: null,
18 paymentToken: null,
19});

onSuccess

The onSuccess callback is called when a user successfully links an Item. It takes two arguments: the public_token and a metadata object.

onSuccess
public_token
string
Displayed once a user has successfully linked their Item.
metadata
object
Displayed once a user has successfully linked their Item.
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
accounts
object
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.
type
string
The account type. See the Account schema for a full list of possible values
subtype
string
The account subtype. See the Account schema for a full list of possible values
verification_status
nullable string
Indicates an Item's micro-deposit-based 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: micro-deposit-based verification is not being used for the Item.
class_type
nullable string
If micro-deposit verification is being used, indicates whether the account being verified is a business or personal account.
account
deprecatednullable object
Deprecated. Use accounts instead.
link_session_id
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.
transfer_status
nullable string
The status of a transfer. Returned only when Transfer UI is implemented.
  • COMPLETE – The transfer was completed.
  • INCOMPLETE – The transfer could not be completed. For help, see Troubleshooting transfers.


Possible values: COMPLETE, INCOMPLETE
Copy
1const handler = Plaid.create({
2 ...,
3 onSuccess: (public_token, metadata) => {
4 fetch('//yourserver.com/exchange_public_token', {
5 method: 'POST',
6 body: {
7 public_token: public_token,
8 accounts: metadata.accounts,
9 institution: metadata.institution,
10 link_session_id: metadata.link_session_id,
11 },
12 });
13 }
14});
Copy
1{
2 institution: {
3 name: 'Wells Fargo',
4 institution_id: 'ins_4'
5 },
6 accounts: [
7 {
8 id: 'ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy',
9 name: 'Plaid Checking',
10 mask: '0000',
11 type: 'depository',
12 subtype: 'checking',
13 verification_status: ''
14 },
15 {
16 id: '9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4',
17 name: 'Plaid Saving',
18 mask: '1111',
19 type: 'depository',
20 subtype: 'savings'
21 }
22 ...
23 ],
24 link_session_id: '79e772be-547d-4c9c-8b76-4ac4ed4c441a'
25}

onExit

The onExit callback is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. It takes two arguments, a nullable error object and a metadata object. The metadata parameter is always present, though some values may be null.

onExit
error
nullable object
A nullable object that contains the error type, code, and message of the error that was last encountered by the user. If no error was encountered, error will be null.
error_type
String
A broad categorization of the error.
error_code
String
The particular error code. Each error_type has a specific set of error_codes.
error_message
String
A developer-friendly representation of the error code.
display_message
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.
metadata
object
Displayed once a user has successfully linked their Item.
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
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_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
requires_oauth
User prompted to enter an OAuth flow
institution_not_found
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
link_session_id
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.
request_id
string
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.
Copy
1const handler = Plaid.create({
2 ...,
3 onExit: (error, metadata) => {
4 // Save data from the onExit handler
5 supportHandler.report({
6 error: error,
7 institution: metadata.institution,
8 link_session_id: metadata.link_session_id,
9 plaid_request_id: metadata.request_id,
10 status: metadata.status,
11 });
12 },
13});
Copy
1{
2 error_type: 'ITEM_ERROR',
3 error_code: 'INVALID_CREDENTIALS',
4 error_message: 'the credentials were not correct',
5 display_message: 'The credentials were not correct.',
6}
Copy
1{
2 institution: {
3 name: 'Wells Fargo',
4 institution_id: 'ins_4'
5 },
6 status: 'requires_credentials',
7 link_session_id: '36e201e0-2280-46f0-a6ee-6d417b450438',
8 request_id: '8C7jNbDScC24THu'
9}

onEvent

The onEvent callback is called at certain points in the Link flow. It takes two arguments, an eventName string and a metadata object.
The metadata parameter is always present, though some values may be null. Note that new eventNames, metadata keys, or view names may be added without notice.
The onEvent callback is not guaranteed to fire exactly at the time of a user action in Link. If you need to determine the exact time when an event happened, use the timestamp in the metadata.
The following callback events 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 instution's routing_number was provided when calling /link/token/create. To distinguish between the two scenarios, see metadata.match_reason.
MATCHED_SELECT_VERIFY_METHOD
The user selected a verification method for a matched institution. This event is emitted 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 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.
SEARCH_INSTITUTION
The user has searched for an institution.
SELECT_AUTH_TYPE
The user has chosen whether to Link instantly or manually (i.e., with micro-deposits). This event emits the selection metadata to indicate the user's selection.
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_DOCUMENTS
The user is being prompted to submit documents for an Income verification flow.
SUBMIT_DOCUMENTS_ERROR
The user encountered an error when submitting documents for an Income verification flow.
SUBMIT_DOCUMENTS_SUCCESS
The user has successfully submitted documents for an Income verification flow.
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.
VIEW_DATA_TYPES
The user has viewed data types on the data transparency consent pane.
metadata
object
An object containing information about the event.
account_number_mask
nullable 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.
error_type
nullable string
The error type that the user encountered. Emitted by: ERROR, EXIT.
error_code
nullable string
The error code that the user encountered. Emitted by ERROR, EXIT.
error_message
nullable string
The error message that the user encountered. Emitted by: ERROR, EXIT.
exit_status
nullable string
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT
institution_id
nullable string
The ID of the selected institution. Emitted by: all events.
institution_name
nullable string
The name of the selected institution. Emitted by: all events.
institution_search_query
nullable string
The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
match_reason
nullable string
The reason this institution was matched, which will be either returning_user or routing_number. Emitted by: MATCHED_SELECT_INSTITUTION
routing_number
nullable string
The routing number submitted by user at the micro-deposits routing number pane. Emitted by SUBMIT_ROUTING_NUMBER.
mfa_type
nullable 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
view_name
nullable 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.
request_id
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.
link_session_id
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.
timestamp
string
An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.
selection
nullable 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.
Copy
1const handler = Plaid.create({
2 ...,
3 onEvent: (eventName, metadata) => {
4 // send event and metadata to self-hosted analytics
5 analytics.send(eventName, metadata);
6 },
7});
Copy
1{
2 error_type: 'ITEM_ERROR',
3 error_code: 'INVALID_CREDENTIALS',
4 error_message: 'the credentials were not correct',
5 exit_status: null,
6 institution_id: 'ins_4',
7 institution_name: 'Wells Fargo',
8 institution_search_query: 'wellsf',
9 mfa_type: null,
10 view_name: 'ERROR'
11 request_id: 'm8MDnv9okwxFNBV',
12 link_session_id: '30571e9b-d6c6-42ee-a7cf-c34768a8f62d',
13 timestamp: '2017-09-14T14:42:19.350Z',
14}

open()

Calling open will display the Consent Pane view to your user, starting the Link flow. Once open is called, you will begin receiving events via the onEvent callback.

Copy
1const handler = Plaid.create({ ... });
2
3// Open Link
4handler.open();

exit()

The exit function allows you to programmatically close Link. Calling exit will trigger either the onExit or onSuccess callbacks.
The exit function takes a single, optional argument, a configuration Object.

exit
force
boolean
If true, Link will exit immediately. If false, or the option is not provided, an exit confirmation screen may be presented to the user.
Copy
1const handler = Plaid.create({ ... });
2
3// Graceful exit - Link may display a confirmation screen
4// depending on how far the user is in the flow
5handler.exit();
Copy
1const handler = Plaid.create({ ... });
2
3// Force exit - Link exits immediately
4handler.exit({ force: true });

destroy()

The destroy function allows you to destroy the Link handler instance, properly removing any DOM artifacts that were created by it. Use destroy() when creating new replacement Link handler instances in the onExit callback.

Copy
1const handler = Plaid.create({ ... })
2
3// Destroy and clean up the Link handler & iFrame
4handler.destroy();

Plaid Link for iOS

This section provides instructions for maintaining Plaid integrations using the deprecated public_key parameter. These instructions cannot be used for new integrations or for adding OAuth support to existing integrations. For up-to-date content on this topic, see the Link iOS SDK instead. For instructions on updating an existing legacy integration, see the Link token migration guide.

Overview

Here you find instructions on how to integrate and use Plaid Link for iOS. At the center of it lies LinkKit.framework: an embeddable framework managing the details of linking an account with Plaid.

To get up and running quickly with Plaid Link for iOS clone the Github repository and try out the example applications, which provide a reference implementation in Swift and Objective-C. Youʼll want to sign up for free API keys to get started.

Installation

Plaid Link for iOS is an embeddable framework that is bundled and distributed within your application. There are several ways to obtain the necessary files and keep them up-to-date; we recommend using CocoaPods or Carthage. Regardless of what you choose, submitting a new version of your application with the updated LinkKit.framework to the App Store is required.

Requirements
  • Xcode 7 or greater
  • iOS 9.0 or greater
  • A Plaid public_key, available from the Plaid Dashboard
  • The latest version of the LinkKit.framework

A new version of LinkKit.framework will be released around the 15th of every month. We recommend you keep up to date to provide the best Plaid Link experience in your application.

CocoaPods
  1. If you haven't already, install the latest version of CocoaPods.
  2. If you don't have an existing Podfile, run the following command to create one:
    Copy
    1pod init
  3. Add this line to your Podfile:
    Copy
    1pod 'Plaid'
  4. Run the following command:
    Copy
    1pod install
  5. Add a custom Run Script build phase (we recommend naming it Prepare for Distribution ) with the script below, which prepares the LinkKit.framework for distribution through the App Store.
    Select Language
    Copy
    1LINK_ROOT=${PODS_ROOT:+$PODS_ROOT/Plaid/ios}
    2cp "${LINK_ROOT:-$PROJECT_DIR}"/LinkKit.framework/prepare_for_distribution.sh "${CODESIGNING_FOLDER_PATH}"/Frameworks/LinkKit.framework/prepare_for_distribution.sh
    3"${CODESIGNING_FOLDER_PATH}"/Frameworks/LinkKit.framework/prepare_for_distribution.sh
  6. To update to newer releases in the future run:
    Copy
    1pod install
Carthage
  1. If you haven't already, install the latest version of Carthage.
  2. If you don't have an existing Podfile, run the following command to create one:
    Copy
    1pod init
  3. Add this line to your Podfile:
    Copy
    1github "plaid/plaid-link-ios"
  4. Add a custom Run Script build phase (we recommend naming it Prepare for Distribution) with the script below, which prepares the LinkKit.framework for distribution through the App Store.
    Select Language
    Copy
    1LINK_ROOT=${PODS_ROOT:+$PODS_ROOT/Plaid/ios}
    2cp "${LINK_ROOT:-$PROJECT_DIR}"/LinkKit.framework/prepare_for_distribution.sh "${CODESIGNING_FOLDER_PATH}"/Frameworks/LinkKit.framework/prepare_for_distribution.sh
    3"${CODESIGNING_FOLDER_PATH}"/Frameworks/LinkKit.framework/prepare_for_distribution.sh
  5. To update to newer releases in the future run:
    Copy
    1carthage update plaid-ios --platform ios
Manual

Get the latest version of LinkKit.framework and embed it into your application.

Embed LinkKit.framework into your application, for example by dragging and dropping the file onto the Embed Frameworks build phase as shown below.

Depending on the location of the LinkKit.framework on the filesystem you may need to change the Framework Search Paths build setting to avoid the error: fatal error: 'LinkKit/LinkKit.h' file not found. For example, the LinkDemo Xcode projects have it set to FRAMEWORK_SEARCH_PATHS = $(PROJECT_DIR)/../ since the LinkKit.framework file is shared between them and is kept in the directory that also contains the demo project directories.

Finally, add a Run Script build phase (we recommend naming it Prepare for Distribution) with the script below. Be sure to run this build phase after the Embed Frameworks build phase or [CP] Embed Pods Frameworks build phase when integrating using CocoaPods, otherwise LinkKit.framework will not be properly prepared for distribution.

Failing to execute the run script build phase after the embed frameworks build phase very likely get your application rejected during App Store submission or review.

The script below removes from the framework any non-iOS device code that is included to support running LinkKit in the Simulator but that may not be distributed via the App Store.

Failing to run the script below will very likely get your application rejected during App Store submission or review.

Change the \${PROJECT_DIR\}/LinkKit.framework path in the example below according to your setup, and be sure to quote the filepaths when they contain whitespace.

Copy
1LINK_ROOT=\${PODS_ROOT:+$PODS_ROOT/Plaid/ios\}
2cp "\${LINK_ROOT:-$PROJECT_DIR\}"/LinkKit.framework/prepare_for_distribution.sh "\${CODESIGNING_FOLDER_PATH\}"/Frameworks/LinkKit.framework/prepare_for_distribution.sh
3"\${CODESIGNING_FOLDER_PATH\}"/Frameworks/LinkKit.framework/prepare_for_distribution.sh

Implementation

To use Plaid Link for iOS import LinkKit and its symbols into your code.

Select Language
Copy
1import LinkKit
2
3extension ViewController : PLKPlaidLinkViewDelegate {
4
5 // call presentPlaidLink to create + initialize Link
6 func presentPlaidLink() {
7 let linkViewController = PLKPlaidLinkViewController(configuration: PLKConfiguration(...), delegate: self)
8 present(linkViewController, animated: true)
9 }
10
11 // handle didSucceedWithPublicToken delegate method
12 func linkViewController(
13 _ linkViewController: PLKPlaidLinkViewController,
14 didSucceedWithPublicToken publicToken: String,
15 metadata: [String : Any]?) { /* handle success */ }
16
17 // handle didExitWithError delegate method
18 func linkViewController(
19 _ linkViewController: PLKPlaidLinkViewController,
20 didExitWithError error: Error?,
21 metadata: [String : Any]?) { /* handle exit | error */ }
22
23 // handle didHandleEvent delegate method
24 func linkViewController(
25 _ linkViewController: PLKPlaidLinkViewController,
26 didHandleEvent event: String,
27 metadata: [String : Any]?) { /* handle exit | error */ }
28}

Configure & present Link

Starting the Plaid Link for iOS experience is as simple as creating and presenting an instance of PLKPlaidLinkViewController. Then, create an instance of PLKConfiguration and pass that during the initialization of the PLKPlaidLinkViewController.

create_legacy
env
String
The Plaid API environment on which to create user accounts. Valid environments are:
  • .sandbox
  • .development
  • .production
key
String
The public_key associated with your account; available in the Plaid Dashboard.
product
[String]
A list of one or many Plaid product(s) you wish to use. Valid products are:
  • .auth
  • .transactions
  • .identity
  • .assets
  • .investments
  • .liabilities
  • .payment_initiation

Example: [.auth, .transactions]. .balance is not a valid value, the Balance product does not require explicit initialization and will automatically be initialized when any other product is initialized. Only institutions that support all requested products will be shown in Link.
In Production, you will be billed for each product that you specify when initializing Link. Note that a product cannot be removed from an Item once the Item has been initialized with that product. To stop billing on an Item for subscription-based products, such as Liabilities, Investments, and Transactions, remove the Item via /item/remove.
clientName
String
Displayed once a user has successfully linked their Item.
language
nullable String
Specify a Plaid-supported language to localize Link. English will be used by default. Supported languages:
  • English ('en')
  • French ('fr')
  • Spanish ('es')
  • Dutch ('nl')
When using a Link customization profile, language must be set to match the language used in the customization profile.
countryCodes
nullable [String]
Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard. Note that if you initialize with a European country code, your users will see the European consent panel during the Link flow. Supported country codes are:
  • US
  • CA
  • ES
  • FR
  • GB
  • IE
  • NL

If not specified, will default to ['US']. If Link is launched with multiple countryCodes, only products that you are enabled for in all countries will be used by Link.
If a Link customization is being used, the countries configured here should match those in the customization.
To use the Auth features Instant Match, Automated Micro-deposits, or Same-day Micro-deposits, countryCodes must be set to ['US'].
accountSubtypes
Dictionary
By default, Link will only display account types that are compatible with all products supplied in the product parameter. You can further limit the accounts shown in Link by using accountSubtypes to specify the account subtypes to be shown in Link. Only the specified subtypes will be shown. To indicate that all subtypes should be shown, use the value "all". If the accountSubtypes filter is used, any account type for which a filter is not specified will be entirely omitted from Link.
Example value:
{
"depository": ["checking", "savings"],
"credit": ["all"]
}
For a full list of valid types and subtypes, see the Account schema.
For institutions using OAuth, the filter will not affect the list of institutions shown by the bank in the OAuth window.
webhook
String
Specify a webhook to associate with an Item. Plaid fires a webhook when the Item requires updated credentials, when new data is available, or when Auth numbers have been successfully verified.
linkCustomizationName
String
Specify the name of a Link customization created in the Dashboard. The default customization is used if none is provided. When using a Link customization, the language specified in the customization must match the language configured via the language parameter.
oauthNonce
String
An oauthNonce is required to support OAuth authentication flows when launching or re-launching Link on a mobile device and using one or more European country codes. The nonce must be at least 16 characters long.
oauthRedirectUri
String
An oauthRedirectUri is required to support OAuth authentication flows when launching Link on a mobile device and using one or more European country codes. Any redirect URI must also be added to the Allowed redirect URIs list in the developer dashboard. For mobile app integrations, the redirect URI must be registered as an app link (not custom URI) to enable app-to-app authentication flows. You will need to configure an Android App Link or Apple App Association File. Custom URI schemes are not supported; a proper universal link must be used.
oauthStateId
String
An oauthStateId is required to support OAuth authentication flows when re-launching Link on a mobile device and using one or more European country codes.
paymentToken
String
A paymentToken must be specified if you are using the Payment Initiation (UK and Europe) product. This will cause Link to open directly to the Payment Initiation flow. Use the /payment_initiation/payment/token/create endpoint to generate a payment_token.
Select Language
Copy
1let linkConfiguration = PLKConfiguration(
2 env: .sandbox,
3 key: "<YOUR_PLAID_PUBLIC_KEY>",
4 product: [.auth]
5)
6linkConfiguration.clientName = "My application";
7linkConfiguration.language = "en";
8linkConfiguration.countryCodes = ["US", "CA", "GB"];
9linkConfiguration.webhook = "https://webhook.com";
10linkConfiguration.linkCustomizationName = "default";
11linkConfiguration.oauthRedirectUri = "<YOUR_OAUTH_REDIRECT_URI>"
12linkConfiguration.oauthNonce = UUID().uuidString
13
14let linkViewController = PLKPlaidLinkViewController(
15 configuration: linkConfiguration,
16 delegate: self
17)
18
19present(linkViewController, animated: true)

didSucceedWithPublicToken

The closure is called when a user successfully links an Item. It should take a single LinkSuccess argument, containing the publicToken String and a metadata of type SuccessMetadata.

onSuccess
linkSuccess
LinkSuccess
Contains the publicToken and metadata for this successful flow.
publicToken
String
Displayed once a user has successfully linked their Item.
metadata
LinkSuccess
Displayed once a user has successfully linked their Item.
institution
nullable Institution
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'
institutionID
InstitutionID (String)
The Plaid institution identifier
accounts
Array<Account>
A list of accounts attached to the connected Item
id
AccountID (String)
The Plaid account_id
name
String
The official account name
mask
Optional<AccountMask> (Optional<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
AccountSubtype
The account subtype and its type. See Account Types for a full list of possible values.
verificationStatus
Optional<VerificationStatus>
The Item's micro-deposit-based 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.
nil: Micro-deposit-based verification is not being used for the Item.
linkSessionID
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
String
Unprocessed metadata, formatted as JSON, sent from the Plaid API.
Select Language
Copy
1func linkViewController(
2 _ linkViewController: PLKPlaidLinkViewController,
3 didSucceedWithPublicToken publicToken: String,
4 metadata: [String : Any]?
5) {
6 dismiss(animated: true) {
7 // Exchange publicToken with an accessToken on your server
8 NSLog("Successfully linked account!\npublicToken: (publicToken)\nmetadata: (metadata ?? [:])")
9 }
10}
Copy
1{
2 kPLKMetadataInstitutionKey: @{
3 kPLKMetadataInstitutionNameKey: 'Wells Fargo',
4 kPLKMetadataInstitutionIdKey: 'ins_4'
5 },
6 kPLKMetadataAccountsKey: [
7 @{
8 kPLKMetadataIdKey: 'ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy',
9 kPLKMetadataNameKey: 'Plaid Checking',
10 kPLKMetadataMaskKey: '0000',
11 kPLKMetadataTypeKey: 'depository',
12 kPLKMetadataSubtypeKey: 'checking',
13 kPLKMetadataAccountVerificationStatusKey: ''
14 },
15 @{
16 kPLKMetadataIdKey: '9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4',
17 kPLKMetadataNameKey: 'Plaid Saving',
18 kPLKMetadataMaskKey: '1111',
19 kPLKMetadataTypeKey: 'depository',
20 kPLKMetadataSubtypeKey: 'savings'
21 }
22 ...
23 ],
24 kPLKMetadataLinkSessionIdKey: '79e772be-547d-4c9c-8b76-4ac4ed4c441a'
25}

didExitWithError

This optional closure is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. It should take a single LinkExit argument, containing an optional error and a metadata of type ExitMetadata.

onExit
linkExit
LinkExit
Contains the optional error and metadata for when the flow was exited.
error
Optional<ExitError>
An Error type that contains the errorCode, errorMessage, and displayMessage of the error that was last encountered by the user. If no error was encountered, error will be nil.
errorCode
ExitErrorCode
The error code and error type that the user encountered. Each errorCode has an associated errorType, which is a broad categorization of the error.
errorMessage
String
A developer-friendly representation of the error code.
displayMessage
Optional<String>
A user-friendly representation of the error code or nil if the error is not related to user action. This may change over time and is not safe for programmatic use.
metadata
ExitMetadata
Displayed once a user has successfully linked their Item.
status
Optional<ExitStatus>
The status key indicates the point at which the user exited the Link flow.
requiresQuestions
User prompted to answer security question(s).
requiresSelections
User prompted to answer multiple choice question(s).
requiresCode
User prompted to provide a one-time passcode.
chooseDevice
User prompted to select a device on which to receive a one-time passcode.
requiresCredentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution.
requiresAccountSelection
User prompted to select one or more financial accounts to share
institutionNotFound
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
unknown
The exit status has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original exit status as sent by the Plaid API.
institution
Optional<Institution>
An institution object. If the Item was created via Same-Day micro-deposit verification, will be omitted.
institutionID
InstitutionID (String)
The Plaid specific identifier for the institution.
name
String
The full institution name, such as 'Wells Fargo'.
linkSessionID
Optional<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.
requestID
Optional<String>
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.
metadataJSON
RawJSONMetadata (String)
Unprocessed metadata, formatted as JSON, sent from Plaid API.
Select Language
Copy
1func linkViewController(
2 _ linkViewController: PLKPlaidLinkViewController,
3 didExitWithError error: Error?,
4 metadata: [String : Any]?
5) {
6 dismiss(animated: true) {
7 if let error = error {
8 NSLog("Failed to link account due to: (error.localizedDescription)\n metadata: (metadata ?? [:])")
9 self.handleError(error, metadata: metadata)
10 }
11 else {
12 NSLog("Plaid link exited with metadata: (metadata ?? [:])")
13 self.handleExitWithMetadata(metadata)
14 }
15 }
16}
Select Language
Copy
1{
2 kPLKErrorTypeKey: 'ITEM_ERROR',
3 kPLKErrorCodeKey: 'INVALID_CREDENTIALS',
4 kPLKErrorMessageKey: 'the credentials were not correct',
5 kPLKDisplayMessageKey: 'The credentials were not correct.',
6}
Select Language
Copy
1{
2 kPLKMetadataInstitutionKey: @{
3 kPLKMetadataInstitutionNameKey: 'Wells Fargo',
4 kPLKMetadataInstitutionIdKey: 'ins_4'
5 },
6 kPLKMetadataLinkSessionIdKey: '36e201e0-2280-46f0-a6ee-6d417b450438',
7 kPLKMetadataRequestIdKey: '8C7jNbDScC24THu'
8}

didHandleEvent

This optional closure is called when certain events in the Plaid Link flow have occurred, for example, when the user selected an institution. This enables your application to gain further insight into what is going on as the user goes through the Plaid Link flow.
The following onEvent callbacks are stable, which means that they will not be deprecated or changed: open, exit, handoff, selectInstitution, error, bankIncomeInsightsCompleted. The remaining callback events are informational and subject to change.

onEvent
linkEvent
LinkEvent
Contains the eventName and metadata for the Link event.
eventName
EventName
An enum representing the event that has just occurred in the Link flow.
bankIncomeInsightsCompleted
The user has completed the Assets and Bank Income Insights flow.
closeOAuth
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 errorCode in the `metadata.
exit
The user has exited without completing the Link flow and the onExit callback is fired.
failOAuth
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.
identityVerificationStartStep
The user has started a step of the Identity Verification flow. The step is indicated by view_name.
identityVerificationPassStep
The user has passed a step of the Identity Verification flow. The step is indicated by view_name.
identityVerificationFailStep
The user has failed a step of the Identity Verification flow. The step is indicated by view_name.
identityVerificationReviewStep
The user has reached the pending review state.
identityVerificationCreateSession
The user has started a new Identity Verification session.
identityVerificationResumeSession
The user has resumed an existing Identity Verification session.
identityVerificationPassSession
The user has successfully completed their Identity Verification session.
identityVerificationFailSession
The user has failed their Identity Verification session.
identityVerificationOpenUI
The user has opened the UI of their Identity Verification session.
identityVerificationResumeUI
The user has resumed the UI of their Identity Verification session.
identityVerificationCloseUI
The user has closed the UI of their Identity Verification session.
matchedSelectInstitution
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 metadata.matchReason.
matchedSelectVerifyMethod
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.
openMyPlaid
The user has opened my.plaid.com. This event is only sent when Link is initialized with Assets as a product.
openOAuth
The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.
searchInstitution
The user has searched for an institution.
selectBrand
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.
selectInstitution
The user selected an institution.
submitCredentials
The user has submitted credentials.
submitMFA
The user has submitted MFA.
transitionView
The transitionView event indicates that the user has moved from one view to the next.
viewDataTypes
The user has viewed data types on the data transparency consent pane.
unknown
The event has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original event name as sent by the Plaid API.
metadata
EventMetadata struct
An object containing information about the event
accountNumberMask
Optional<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
Optional<ExitErrorCode>
The error code that the user encountered. Emitted by: error, exit.
errorMessage
Optional<String>
The error message that the user encountered. Emitted by: error, exit.
exitStatus
Optional<ExitStatus>
The status key indicates the point at which the user exited the Link flow. Emitted by: exit.
requiresQuestions
User prompted to answer security question(s).
requiresSelections
User prompted to answer multiple choice question(s).
requiresCode
User prompted to provide a one-time passcode.
chooseDevice
User prompted to select a device on which to receive a one-time passcode.
requiresCredentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution.
institutionNotFound
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
unknown
The exit status has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original exit status as sent by the Plaid API.
institutionID
Optional<InstitutionID> (Optional<String>)
The ID of the selected institution. Emitted by: all events.
institutionName
Optional<String>
The name of the selected institution. Emitted by: all events.
institutionSearchQuery
Optional<String>
The query used to search for institutions. Emitted by: searchInstitution.
matchReason
nullable string
The reason this institution was matched, which will be either returning_user or routing_number. Emitted by: matchedSelectInstitution.
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
Optional<MFAType>
If set, the user has encountered one of the following MFA types: code, device, questions, selections. Emitted by: submitMFA and transitionView when viewName is mfa
requestID
Optional<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.
routingNumber
Optional<String>
The routing number submitted by user at the micro-deposits routing number pane. Emitted by SUBMIT_ROUTING_NUMBER.
selection
Optional<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
Date
An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.
viewName
Optional<ViewName>
The name of the view that is being transitioned to. Emitted by: transitionView.
acceptTOS
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.
dataTransparency
We disclose the data types being shared.
dataTransparencyConsent
We ask the user to consent to the privacy policy and disclose data types being shared.
documentaryVerification
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.
kycCheck
The view representing the "know your customer" step in the identity verification flow.
loading
Link is making a request to our servers.
matchedConsent
We ask the matched user to consent to the privacy policy and SMS terms.
matchedCredential
We ask the matched user for their account credentials to a matched institution.
matchedMfa
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.
riskCheck
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.
selectAccount
We ask the user to choose an account.
selectAuthType
The user is asked to choose whether to Link instantly or manually (i.e., with micro-deposits).
selectBrand
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.
selectInstitution
We ask the user to choose their institution.
selfieCheck
The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.
uploadDocuments
The user is asked to upload documents (for Income verification).
verifySMS
The SMS verification step in the identity verification flow.
unknown
The view has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original view name as sent by the Plaid API.
metadataJSON
RawJSONMetadata (String)
Unprocessed metadata, formatted as JSON, sent from Plaid API.
Select Language
Copy
1func linkViewController(
2 _ linkViewController: PLKPlaidLinkViewController,
3 didHandleEvent event: String,
4 metadata: [String : Any]?
5) {
6 NSLog("Link event: (event)\nmetadata: (metadata ?? [:])")
7}
Select Language
Copy
1{
2 kPLKMetadataErrorTypeKey: 'ITEM_ERROR',
3 kPLKMetadataErrorCodeKey: 'INVALID_CREDENTIALS',
4 kPLKMetadataErrorMessageKey: 'the credentials were not correct',
5 kPLKMetadataExitStatusKey: '',
6 kPLKMetadataInstitutionIdKey: 'ins_4',
7 kPLKMetadataInstitutionNameKey: 'Wells Fargo',
8 kPLKMetadataInstitutionSearchQueryKey: 'wellsf',
9 kPLKMetadataLinkSessionIdKey: '30571e9b-d6c6-42ee-a7cf-c34768a8f62d',
10 kPLKMetadataMFATypeKey: '',
11 kPLKMetadataRequestIdKey: 'm8MDnv9okwxFNBV',
12 kPLKMetadataTimestampKey: '2017-09-14T14:42:19.350Z',
13 kPLKMetadataViewNameKey: 'ERROR'
14}

Plaid Link for Android

This section provides instructions for maintaining Plaid integrations using the deprecated public_key parameter. These instructions cannot be used for new integrations or for adding OAuth support to existing integrations. For up-to-date content on this topic, see the Link Android SDK instead. For instructions on updating an existing legacy integration, see the Link token migration guide.

Overview

Here you find instructions on how to integrate and use Plaid Link for Android. At the center of it lies LinkSdk: an embeddable framework managing the details of linking an account with Plaid.

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

Requirements

  • The latest version of Android Studio
  • A Plaid client_id and secret, available from the Plaid Dashboard
  • Android 5.0 (API level 21) and above

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.

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 jcenter() // Include to import Plaid Link transitive dependencies
7 }
8 dependencies {
9 // ...
10 }
11}
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}
Register your app ID

To register your Android app ID:

  1. Log in to the Plaid Dashboard
  2. Navigate to the API pane on the Team Settings page
  3. Configure one or more Android package names (e.g.com.plaid.example)
  4. Save your changes

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

Initialize Plaid Link Instance

Create an instance of Plaid Link by calling Plaid.initialize(application). Try to do this as early as possible to speed up opening Plaid Link.

Select Language
Copy
1import android.app.Application
2import com.plaid.link.Plaid
3
4class MyApplication : Application() {
5
6 override fun onCreate() {
7 super.onCreate()
8 Plaid.intialize(this)
9 }

Open Link

The Plaid object can be used to open Link with the given configuration. With Kotlin you can use the openPlaidLink extension function from an Activity or Fragment.

create_legacy
accountSubtypes
List
By default, Link will only display account types that are compatible with all products supplied in the product parameter. You can further limit the accounts shown in Link by using accountSubtypes to specify the account subtypes to be shown in Link. Only the specified subtypes will be shown. To indicate that all subtypes should be shown, use the value "all". If the accountSubtypes filter is used, any account type for which a filter is not specified will be entirely omitted from Link.
Example value:
{
"depository": ["checking", "savings"],
"credit": ["all"]
}
For a full list of valid types and subtypes, see the Account schema.
For institutions using OAuth, the filter will not affect the list of institutions shown by the bank in the OAuth window.
clientName
String
Displayed once a user has successfully linked their Item.
countryCodes
List
Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard. Accepted values must use the native Android Locale country. If Link is launched with multiple countryCodes only products that you are enabled for in all specified countries will be available. Supported countries:
  • Canada: Locale.CA.country
  • France: Locale.FR.country
  • Ireland: Locale.IE.country
  • Netherlands: Locale.NL.country
  • Spain: Locale.ES.country
  • United Kingdom: Locale.UK.country
  • United States: Locale.US.country
If a Link customization is being used, the countries configured here should match those in the customization.
To use the Auth features Instant Match, Automated Micro-deposits, or Same-day Micro-deposits, countryCodes must be set to [Locale.US.country].
environment
String
The Plaid API environment on which to create user accounts. Available environments
  • Sandbox: PlaidEnvironment.SANDBOX
  • Development: PlaidEnvironment.DEVELOPMENT
  • Production: PlaidEnvironment.PRODUCTION
language
String
Specify a Plaid-supported language to localize Link. Accepted values must use the native Android Locale Language. English will be used by default. Supported languages:
  • English: Locale.ENGLISH.language
  • French: Locale.FRENCH.language
  • Spanish: Locale.SPANISH.language
  • Dutch: Locale.DUTCH.language
When using a Link customization, language must be set to match the language used in the customization.
products
List
A list of Plaid product(s) you wish to use. Only institutions that support all requested products will be shown in Link. Valid products:
  • Auth: PlaidProduct.AUTH
  • Transactions: PlaidProduct.TRANSACTIONS
  • Identity: PlaidProduct.IDENTITY
  • Assets: PlaidProduct.ASSETS
  • Investments: PlaidProduct.INVESTMENTS
  • Liabilities: PlaidProduct.LIABILITIES
  • PaymentInitiation: PlaidProduct.PAYMENT_INITIATION

In Production, you will be billed for each product that you specify when initializing Link. Note that a product cannot be removed from an Item once the Item has been initialized with that product. To stop billing on an Item for subscription-based products, such as Liabilities, Investments, and Transactions, remove the Item via /item/remove.
linkCustomizationName
String
Specify the name of a Link customization created in the Dashboard. The default customization is used if none is provided. When using a Link customization, the language specified in the customization must match the language configured via the language parameter.
logLevel
enum
Set the level at which to log statements. Possible values are ASSERT, DEBUG, ERROR, INFO, VERBOSE, and WARN.
publicKey
String
The public_key associated with your account; available from the Dashboard.
token
string
Specify a payment_token or access_token. For link_token use a LinkTokenConfiguration instead.
userLegalName
string
The end user's legal name
userPhoneNumber
string
The end user's phone number
userEmailAddress
string
The end user's email address
webhook
String
Specify a webhook to associate with an Item. Plaid fires a webhook when the Item requires updated credentials, when new data is available, or when Auth numbers have been successfully verified.
extraParams
deprecatedmap<string, string>
Any additional params that need to be passed into the SDK can be added here.
Select Language
Copy
1import android.content.Intent
2import com.plaid.link.Plaid
3import com.plaid.linkbase.models.LinkConfiguration
4import com.plaid.linkbase.models.PlaidEnvironment
5import com.plaid.linkbase.models.PlaidProduct
6import com.plaid.link.configuration.LinkLogLevel
7
8class MainActivity : AppCompatActivity() {
9
10 override fun onCreate(savedInstanceState: Bundle?) {
11 super.onCreate(savedInstanceState)
12
13 // Open Link – this will usually be in a click listener
14 this@MainActivity.openPlaidLink(
15 linkConfiguration = linkConfiguration {
16 environment = PlaidEnvironment.SANDBOX
17 products = listOf(PlaidProduct.TRANSACTIONS)
18 clientName = "My Application name"
19 language = Locale.ENGLISH.language
20 countryCodes = listOf(Locale.US.country)
21 webhook = "https://requestb.in"
22 linkCustomizationName = "default"
23 publicToken = null
24 paymentToken = null
25 }
26 )
27 }
28}

Handling Results and Events

The onActivityResult handler is called for the onSuccess and onExit events. Use PlaidLinkResultHandler to parse the result out of the returned intent.

Select Language
Copy
1import android.content.Intent
2
3import com.plaid.link.LinkActivity
4import com.plaid.link.Plaid
5import com.plaid.linkbase.models.LinkEventListener
6import com.plaid.linkbase.models.PlaidApiError
7import com.plaid.linkbase.models.PlaidEnvironment
8import com.plaid.linkbase.models.PlaidProduct
9
10class MainActivity : AppCompatActivity() {
11
12 private val resultHandler = PlaidLinkResultHandler(
13 onSuccess = { it: LinkConnection -> /* handle onSuccess */ }
14 onExit = { it: PlaidError -> /* handle onExit */ }
15 )
16
17 override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
18 super.onActivityResult(requestCode, resultCode, data)
19 if (!resultHandler.onActivityResult(requestCode, resultCode, data)) {
20 Log.i(MainActivity.class.getSimpleName(), "Not handled");
21 }
22 }
23
24 override fun onCreate(savedInstanceState: Bundle?) {
25 super.onCreate(savedInstanceState)
26
27 Plaid.setLinkEventListener { event -> Log.i("Event", event.toString()) }
28
29 ...
30 }
31}

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
1class MainActivity : AppCompatActivity() {
2
3 private val resultHandler = PlaidLinkResultHandler(
4 // ...
5 onSuccess = { it: LinkConnection ->
6 // Send public_token to your server, exchange for access_token
7 val publicToken = it.publicToken
8
9 val metadata = it.linkConnectionMetadata
10 val accountId = metadata.accounts.first().accountId
11 val accountName = metadata.accounts.first().accountName
12 val accountNumber = metadata.accounts.first().accountNumber
13 val accountType = metadata.accounts.first().accountType
14 val accountSubType = metadata.accounts.first().accountSubType
15 val institutionId = metadata.institutionId
16 val institutionName = metadata.institutionName
17 }
18 )
19}

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
1class MainActivity : AppCompatActivity() {
2
3 private val resultHandler = PlaidLinkResultHandler(
4 // ...
5 onExit = {
6 PlaidError error = it.error?
7 String errorType = error.errorType
8 String errorCode = error.errorCode
9 String errorMessage = error.errorMessage
10 String displayMessage = error.displayMessage
11
12 LinkExitMetadata metadata = it.linkExitMetadata
13 String institutionId = metadata.institutionId
14 String institutionName = metadata.institutionName
15 String linkSessionId = metadata.linkSessionId;
16 String requestId = metadata.requestId;
17 },
18 )
19}

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
1class MainActivity : AppCompatActivity() {
2
3 override fun onCreate(savedInstanceState: Bundle?) {
4
5 Plaid.setLinkEventListener(linkEventListener = {
6 Log.i("Event", it.toString())
7 })
8 }
9}

Plaid Link for React Native

This section provides instructions for maintaining Plaid integrations using the deprecated public_key parameter. These instructions cannot be used for new integrations or for adding OAuth support to existing integrations. For up-to-date content on this topic, see the Link React Native SDK instead. For instructions on updating an existing legacy integration, see the Link token migration guide.

To get started with Plaid Link for React Native youʼll want to sign up for free API keys through the Plaid Developer Dashboard.

Requirements

  • React Native Version 0.61.3 or higher
  • See the Android setup guide and iOS setup guide for platform-specific requirements

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

Version Compatibility
React Native SDKAndroid SDKiOS SDKStatus
7.x.x3.2.x>=2.0.7Active
6.x.x3.x.x>=2.0.1Active
5.x.x2.1.x>=1.1.34Active
4.x.x2.0.x<=1.1.33Active
3.x.x1.x.x<=1.1.33Deprecated
2.x.x0.3.x<=1.1.27Deprecated
1.x.x< 0.3.x<=1.1.24Deprecated

Getting Started

Installing the SDK

In your react-native project directory, run:

Copy
1npm install --save react-native-plaid-link-sdk

Next Steps

  • To set up the SDK for use in your Android application, see the Android setup guide.
  • To set up the SDK for use in your iOS application, see the iOS setup guide.
PlaidLink

PlaidLink is the the React component used to open Link from a React Native application. PlaidLink renders a Pressable component, which wraps the component you provide and intercepts onPress events to open Link.

plaidLink_legacy
onSuccess
LinkSuccessListener
A function that is called when a user successfully links an Item. The function should expect one argument.
publicKeyConfig
deprecatedLinkPublicKeyConfiguration
A configuration used to open Link with a a public key
publicKey
String
The public_key associated with your account; available from the Dashboard.
oauthConfiguration
Values used to configure the application for OAuth
oauthNonce
string
An oauthNonce is required to support OAuth authentication flows when launching or re-launching Link on a mobile device and using one or more European country codes. The nonce must be at least 16 characters long.
oauthRedirectUri
An oauthRedirectUri is required to support OAuth authentication flows when launching Link on a mobile device and using one or more European country codes. Note that any redirect URI must also be added to the Allowed redirect URIs list in the developer dashboard.
clientName
string
Displayed once a user has successfully linked their Item.
countryCodes
Array<string>
Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard. Note that if you initialize with a European country code, your users will see the European consent panel during the Link flow. Supported country codes are: US, CA, ES, FR, GB, IE, NL. If not specified, will default to ['US']. If Link is launched with multiple countryCodes, only products that you are enabled for in all countries will be used by Link.
If a Link customization is being used, the countries configured here should match those in the customization.
environment
PlaidEnvironment
The Plaid API environment on which to create user accounts. Possible values are sandbox, development, and production.
product
Array<PlaidProduct>
A list of Plaid products you wish to use. Valid products are: transactions, auth, identity, assets, investments, liabilities, and payment_initiation. Example: ['auth', 'transactions']. balance is not a valid value, the Balance product does not require explicit initalization and will automatically be initialized when any other product is initialized. Only institutions that support all requested products will be shown in Link.
In Production, you will be billed for each product that you specify when initializing Link. Note that a product cannot be removed from an Item once the Item has been initialized with that product. To stop billing on an Item for subscription-based products, such as Liabilities, Investments, and Transactions, remove the Item via /item/remove.
accountSubtypes
Array<LinkAccountSubtype>
By default, Link will only display account types that are compatible with all products supplied in the product parameter. You can further limit the accounts shown in Link by using accountSubtypes to specify the account subtypes to be shown in Link. Only the specified subtypes will be shown. To indicate that all subtypes should be shown, use the value "all". If the accountSubtypes filter is used, any account type for which a filter is not specified will be entirely omitted from Link.
Example value:
{
"depository": ["checking", "savings"],
"credit": ["all"]
}
For a full list of valid types and subtypes, see the Account schema.
For institutions using OAuth, the filter will not affect the list of institutions shown by the bank in the OAuth window.
linkCustomizationName
string
Specify the name of a Link customization created in the Dashboard. The default customization is used if none is provided. When using a Link customization, the language in the customization must match the language configured via the language parameter.
token
string
Specify a link_token to authenticate your app with Link. This is a short lived, one-time use token that should be unique for each Link session. In addition to the primary flow, a link_token can be configured to launch Link in update mode for Items with expired credentials, or the Payment Initiation (UK and Europe) flow. See the /link/token/create endpoint for a full list of configurations.
userLegalName
string
The end user's legal name
userPhoneNumber
string
The end user's phone number
userEmailAddress
string
The end user's email address
webhook
string
Specify a webhook to associate with an Item. Plaid fires a webhook when the Item requires updated credentials, when new data is available, or when Auth numbers have been successfully verified.
logLevel
LinkLogLevel
Set the level at which to log statements

Possible values: DEBUG, INFO, WARN, ERROR
extraParams
Record<string, any>
You do not need to use this field unless specifically instructed to by Plaid.
onExit
LinkExitListener
A function that is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The function should expect one argument.
children
React.ReactNode
The underlying component to render
Copy
1<PlaidLink
2 publicKeyConfig={{
3 clientName: 'Client Name',
4 publicKey: '<INSERT PUBLIC KEY>',
5 environment: PlaidEnvironment.SANDBOX,
6 products: Array.of(PlaidProduct.AUTH),
7 language: 'en',
8 countryCodes: Array.of('US'),
9 logLevel: LinkLogLevel.DEBUG,
10 oauthConfiguration: {
11 nonce: '',
12 redirectUri: 'https://myapp.example.com',
13 },
14 }}
15 onSuccess={(success: LinkSuccess) => {
16 console.log(success);
17 }}
18 onExit={(exit: LinkExit) => {
19 console.log(exit);
20 }}
21>
22 <Text>Add Account</Text>
23</PlaidLink>

onSuccess

The onSuccess callback returns a LinkSuccess object.

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
LinkSuccessMetadata
Displayed once a user has successfully linked their Item.
accounts
Array<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
nullable 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.
type
LinkAccountType
The account type. See the Account schema for a full list of possible values
subtype
LinkAccountSubtype
The account subtype. See the Account schema for a full list of possible values
verification_status
nullable LinkAccountVerificationStatus
Indicates an Item's micro-deposit-based verification status.
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'
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.
Copy
1const onSuccess = (success: LinkSuccess) => {
2 fetch('https://yourserver.com/get_access_token', {
3 method: 'POST',
4 body: {
5 publicToken: linkSuccess.publicToken,
6 accounts: linkSuccess.metadata.accounts,
7 institution: linkSuccess.metadata.institution,
8 linkSessionId: linkSuccess.metadata.linkSessionId,
9 },
10 });
11};

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 info in Plaid Support requests for the user.

onExit
error
LinkError
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
LinkErrorCode
The particular error code. Each errorType has a specific set of errorCodes. A code of 499 indicates a client-side exception.
errorType
LinkErrorType
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.
metadata
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 LinkInstitution
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'
id
string
The Plaid institution identifier
status
nullable LinkExitMetadataStatus
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
requires_oauth
User prompted to enter an OAuth flow
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
metadataJson
nullable Map
The data directly returned from the server with no client side changes.
Copy
1const onExit = (linkExit: LinkExit) => {
2 supportHandler.report({
3 error: linkExit.error,
4 institution: linkExit.metadata.institution,
5 linkSessionId: linkExit.metadata.linkSessionId,
6 requestId: linkExitlinkExit.metadata.requestId,
7 status: linkExit.metadata.status,
8 });
9};

onEvent

The React Native Plaid module emits onEvent events throughout the account linking process. To receive these events use the usePlaidEmitter hook.

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
LinkEventName
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 metadata.matchReason.
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 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.
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.
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.
metadata
LinkEventMetadata
An object containing information about the event.
submitAccountNumber
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 linkSessionId 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
LinkEventViewName
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.
Copy
1usePlaidEmitter((event: LinkEvent) => {
2 console.log(event);
3});

OAuth

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

Upgrading

  • To upgrade from version 6.x to 7.x, see the 6.x to 7.x migration guide.
  • To upgrade from version 5.x to 7.x, see the 5.x to 7.x migration guide.

Plaid Link for Webviews

This section provides instructions for maintaining Plaid integrations using the deprecated public_key parameter. These instructions cannot be used for new integrations or for adding OAuth support to existing integrations. For up-to-date content on this topic, see the Link Webview SDK instead. For instructions on updating an existing legacy integration, see the Link token migration guide.

Here you will find instructions on how to integrate and use Plaid Link inside a Webview. We recommend starting with one of our sample Webview apps:

  • iOS WKWebView
  • Android Webview

Each example app is runnable (on both simulators and devices) and includes code to initialize Link and process events sent from Link to your app via HTTP redirects.

Installation

Link is optimized to work within Webviews, including on iOS and Android. The Link initialization URL to use for Webviews is:

Copy
1https://cdn.plaid.com/link/v2/stable/link.html

The Link configuration options for a Webview integration are passed via querystring rather than via a client-side JavaScript call. See the create section below for details on the available initialization parameters.

Communication between Link and your app

Communication between the Webview and your app is handled by HTTP redirects rather than client-side JavaScript callbacks. These redirects should be intercepted by your app. The example apps include sample code to do this.

All redirect URLs have the scheme plaidlink. The event type is communicated via the URL host and data is passed via the querystring.

Copy
1plaidlink://

There are three supported events, connected, exit, and event, which are documented below.

Create

create_legacy
isWebview
boolean
Set to true, to trigger the Webview integration.
clientName
string
Displayed once a user has successfully linked their Item.
env
string
The Plaid API environment on which to create user accounts. Possible values are development, sandbox, respectively. For Production use, use production.
key
string
The public_key associated with your account; available from the Dashboard.
product
string
A list of Plaid products you wish to use. Valid products are: transactions, auth, identity, assets, investments, liabilities, and payment_initiation. Example: auth,transactions. balance is not a valid value, the Balance product does not require explicit initialization and will automatically be initialized when any other product is initialized. Only institutions that support all requested products will be shown in Link.
In Production, you will be billed for each product that you specify when initializing Link. Note that a product cannot be removed from an Item once the Item has been initialized with that product. To stop billing on an Item for subscription-based products, such as Liabilities, Investments, and Transactions, remove the Item via /item/remove.
language
string
Specify a Plaid-supported language to localize Link. English will be used by default. Supported languages:
  • English (en)
  • French (fr)
  • Spanish (es)
  • Dutch (nl)
When using a Link customization, language must be set to match the language used in the customization.
countryCodes
string
Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard. Note that if you initialize with a European country code, your users will see the European consent panel during the Link flow. Supported country codes are: US, CA, ES, FR, GB, IE, NL. If not specified, will default to ['US']. If Link is launched with multiple countryCodes, only products that you are enabled for in all countries will be used by Link.
If a Link customization is being used, the countries configured here should match those in the customization.
To use the Auth features Instant Match, Automated Micro-deposits, or Same-day Micro-deposits, countryCodes must be set to ['US'].
accountSubtypes
object
By default, Link will only display account types that are compatible with all products supplied in the product parameter. You can further limit the accounts shown in Link by using accountSubtypes to specify the account subtypes to be shown in Link. Only the specified subtypes will be shown. To indicate that all subtypes should be shown, use the value "all". If the accountSubtypes filter is used, any account type for which a filter is not specified will be entirely omitted from Link.
Example value:
{
"depository": ["checking", "savings"],
"credit": ["all"]
}
For a full list of valid types and subtypes, see the Account schema.
For institutions using OAuth, the filter will not affect the list of institutions shown by the bank in the OAuth window.
<accountType>: [accountSubtype]