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.
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.
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 . | |
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:
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.
| |
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 |
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.
public_token string Displayed once a user has successfully linked their Item. | ||||||||||||||
metadata object Displayed once a user has successfully linked their Item.
|
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});
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
.
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.
| ||||||||||||||
metadata object Displayed once a user has successfully linked their Item.
|
1const handler = Plaid.create({2 ...,3 onExit: (error, metadata) => {4 // Save data from the onExit handler5 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});
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}
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.
eventName string A string representing the event that has just occurred in the Link flow.
| |||||||||||||||||||||||||||||||||||||||||||
metadata object An object containing information about the event.
|
1const handler = Plaid.create({2 ...,3 onEvent: (eventName, metadata) => {4 // send event and metadata to self-hosted analytics5 analytics.send(eventName, metadata);6 },7});
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.
1const handler = Plaid.create({ ... });23// Open Link4handler.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
.
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. |
1const handler = Plaid.create({ ... });23// Graceful exit - Link may display a confirmation screen4// depending on how far the user is in the flow5handler.exit();
1const handler = Plaid.create({ ... });23// Force exit - Link exits immediately4handler.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.
1const handler = Plaid.create({ ... })23// Destroy and clean up the Link handler & iFrame4handler.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
- If you haven't already, install the latest version of CocoaPods.
- If you don't have an existing Podfile, run the following command to create one:1pod init
- Add this line to your
Podfile
:1pod 'Plaid' - Run the following command:1pod install
- 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.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.sh3"${CODESIGNING_FOLDER_PATH}"/Frameworks/LinkKit.framework/prepare_for_distribution.sh
- To update to newer releases in the future run:1pod install
Carthage
- If you haven't already, install the latest version of Carthage.
- If you don't have an existing Podfile, run the following command to create one:1pod init
- Add this line to your
Podfile
:1github "plaid/plaid-link-ios" - 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.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.sh3"${CODESIGNING_FOLDER_PATH}"/Frameworks/LinkKit.framework/prepare_for_distribution.sh - To update to newer releases in the future run: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.
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.sh3"\${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.
1import LinkKit23extension ViewController : PLKPlaidLinkViewDelegate {45 // call presentPlaidLink to create + initialize Link6 func presentPlaidLink() {7 let linkViewController = PLKPlaidLinkViewController(configuration: PLKConfiguration(...), delegate: self)8 present(linkViewController, animated: true)9 }1011 // handle didSucceedWithPublicToken delegate method12 func linkViewController(13 _ linkViewController: PLKPlaidLinkViewController,14 didSucceedWithPublicToken publicToken: String,15 metadata: [String : Any]?) { /* handle success */ }1617 // handle didExitWithError delegate method18 func linkViewController(19 _ linkViewController: PLKPlaidLinkViewController,20 didExitWithError error: Error?,21 metadata: [String : Any]?) { /* handle exit | error */ }2223 // handle didHandleEvent delegate method24 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
.
env String The Plaid API environment on which to create user accounts. Valid environments are:
|
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:
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:
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:
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 . |
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().uuidString1314let linkViewController = PLKPlaidLinkViewController(15 configuration: linkConfiguration,16 delegate: self17)1819present(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
.
linkSuccess LinkSuccess Contains the publicToken and metadata for this successful flow.
|
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 server8 NSLog("Successfully linked account!\npublicToken: (publicToken)\nmetadata: (metadata ?? [:])")9 }10}
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
.
linkExit LinkExit Contains the optional error and metadata for when the flow was exited.
|
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}
1{2 kPLKErrorTypeKey: 'ITEM_ERROR',3 kPLKErrorCodeKey: 'INVALID_CREDENTIALS',4 kPLKErrorMessageKey: 'the credentials were not correct',5 kPLKDisplayMessageKey: 'The credentials were not correct.',6}
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.
linkEvent LinkEvent Contains the eventName and metadata for the Link event.
|
1func linkViewController(2 _ linkViewController: PLKPlaidLinkViewController,3 didHandleEvent event: String,4 metadata: [String : Any]?5) {6 NSLog("Link event: (event)\nmetadata: (metadata ?? [:])")7}
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
andsecret
, 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.
1buildscript {2 repositories {3 // Check that you have the following line (if not, add it):4 google() // Google's Maven repository5 mavenCentral() // Include to import Plaid Link Android SDK6 jcenter() // Include to import Plaid Link transitive dependencies7 }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
and can be found on Maven Central.
1android {2 defaultConfig {3 minSdkVersion 21 // or greater4 }56 // Enable Java 8 support for Link to work7 compileOptions {8 sourceCompatibility JavaVersion.VERSION_1_89 targetCompatibility JavaVersion.VERSION_1_810 }11}1213dependencies {14 // ...15 implementation 'com.plaid.link:sdk-core:<insert latest version>'16}
Register your app ID
To register your Android app ID:
- Log in to the Plaid Dashboard
- Navigate to the API pane on the Team Settings page
- Configure one or more Android package names (e.g.
com.plaid.example
) - 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.
1import android.app.Application2import com.plaid.link.Plaid34class MyApplication : Application() {56 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.
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:
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
|
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:
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:
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. |
1import android.content.Intent2import com.plaid.link.Plaid3import com.plaid.linkbase.models.LinkConfiguration4import com.plaid.linkbase.models.PlaidEnvironment5import com.plaid.linkbase.models.PlaidProduct6import com.plaid.link.configuration.LinkLogLevel78class MainActivity : AppCompatActivity() {910 override fun onCreate(savedInstanceState: Bundle?) {11 super.onCreate(savedInstanceState)1213 // Open Link – this will usually be in a click listener14 this@MainActivity.openPlaidLink(15 linkConfiguration = linkConfiguration {16 environment = PlaidEnvironment.SANDBOX17 products = listOf(PlaidProduct.TRANSACTIONS)18 clientName = "My Application name"19 language = Locale.ENGLISH.language20 countryCodes = listOf(Locale.US.country)21 webhook = "https://requestb.in"22 linkCustomizationName = "default"23 publicToken = null24 paymentToken = null25 }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.
1import android.content.Intent23import com.plaid.link.LinkActivity4import com.plaid.link.Plaid5import com.plaid.linkbase.models.LinkEventListener6import com.plaid.linkbase.models.PlaidApiError7import com.plaid.linkbase.models.PlaidEnvironment8import com.plaid.linkbase.models.PlaidProduct910class MainActivity : AppCompatActivity() {1112 private val resultHandler = PlaidLinkResultHandler(13 onSuccess = { it: LinkConnection -> /* handle onSuccess */ }14 onExit = { it: PlaidError -> /* handle onExit */ }15 )1617 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 }2324 override fun onCreate(savedInstanceState: Bundle?) {25 super.onCreate(savedInstanceState)2627 Plaid.setLinkEventListener { event -> Log.i("Event", event.toString()) }2829 ...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.
publicToken String Displayed once a user has successfully linked their Item. | ||||||||||||
metadata Object Displayed once a user has successfully linked their Item.
|
1class MainActivity : AppCompatActivity() {23 private val resultHandler = PlaidLinkResultHandler(4 // ...5 onSuccess = { it: LinkConnection ->6 // Send public_token to your server, exchange for access_token7 val publicToken = it.publicToken89 val metadata = it.linkConnectionMetadata10 val accountId = metadata.accounts.first().accountId11 val accountName = metadata.accounts.first().accountName12 val accountNumber = metadata.accounts.first().accountNumber13 val accountType = metadata.accounts.first().accountType14 val accountSubType = metadata.accounts.first().accountSubType15 val institutionId = metadata.institutionId16 val institutionName = metadata.institutionName17 }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.
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 .
| |||||||||||||||
LinkExitMetadata Map<String, Object> An object containing information about the exit event
|
1class MainActivity : AppCompatActivity() {23 private val resultHandler = PlaidLinkResultHandler(4 // ...5 onExit = {6 PlaidError error = it.error?7 String errorType = error.errorType8 String errorCode = error.errorCode9 String errorMessage = error.errorMessage10 String displayMessage = error.displayMessage1112 LinkExitMetadata metadata = it.linkExitMetadata13 String institutionId = metadata.institutionId14 String institutionName = metadata.institutionName15 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.
eventName String A string representing the event that has just occurred in the Link flow.
| ||||||||||||||||||||||||||||||||||||||||||||
LinkEventMetadata Map<String, Object> An object containing information about the event.
|
1class MainActivity : AppCompatActivity() {23 override fun onCreate(savedInstanceState: Bundle?) {45 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 SDK | Android SDK | iOS SDK | Status |
---|---|---|---|
7.x.x | 3.2.x | >=2.0.7 | Active |
6.x.x | 3.x.x | >=2.0.1 | Active |
5.x.x | 2.1.x | >=1.1.34 | Active |
4.x.x | 2.0.x | <=1.1.33 | Active |
3.x.x | 1.x.x | <=1.1.33 | Deprecated |
2.x.x | 0.3.x | <=1.1.27 | Deprecated |
1.x.x | < 0.3.x | <=1.1.24 | Deprecated |
Getting Started
Installing the SDK
In your react-native project directory, run:
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_legacyonSuccess 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
| |||||||||||||||||
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 |
1<PlaidLink2 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.
publicToken String Displayed once a user has successfully linked their Item. | |||||||||||||||||||
metadata LinkSuccessMetadata Displayed once a user has successfully linked their Item.
|
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.
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 .
| |||||||||||||||||
metadata Map<String, Object> An object containing information about the exit event
|
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.
eventName LinkEventName A string representing the event that has just occurred in the Link flow.
| |||||||||||||||||||||||||||||||||||||||||||
metadata LinkEventMetadata An object containing information about the event.
|
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:
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:
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.
1plaidlink://
There are three supported events, connected
, exit
, and event
, which are documented below.
Create
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:
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. |