Link Web SDK
Reference for integrating with the Link JavaScript SDK and React SDK
Prefer to learn with code examples? Check out our GitHub repo with working example Link implementations for both JavaScript and React.
Installation
Select group for content switcherInclude the Plaid Link initialize script on each page of your site. It must always be loaded directly from https://cdn.plaid.com
, rather than included in a bundle or hosted yourself. Unlike Plaid's other SDKs, the JavaScript web SDK is not versioned; cdn.plaid.com
will automatically provide the latest available SDK.
1<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
To get started with Plaid Link for React, clone the GitHub repository and review the example application and README, which provide reference implementations.
Next, you'll need to install the react-plaid-link package.
With npm:
1npm install --save react-plaid-link
With yarn:
1yarn add react-plaid-link
Then import the necessary components and types:
1import {2 usePlaidLink,3 PlaidLinkOptions,4 PlaidLinkOnSuccess,5} from 'react-plaid-link';
CSP directives
If you are using a Content Security Policy (CSP), use the following directives to allow Link traffic:
1default-src https://cdn.plaid.com/;2script-src 'unsafe-inline' https://cdn.plaid.com/link/v2/stable/link-initialize.js;3frame-src https://cdn.plaid.com/;4connect-src https://production.plaid.com/;
If using Sandbox instead of Production, make sure to update the connect-src
directive to point to the appropriate server (https://sandbox.plaid.com
).
Creating a Link token
Before you can create an instance of Link, you need to first create a link_token
. A link_token
can be configured for
different Link flows and is used to control much of Link's behavior. To learn how to create a new
link_token
, see the API Reference entry for /link/token/create
.
Create
Plaid.create
accepts one argument, a configuration Object
, and returns an Object
with three functions, open
, exit
, and destroy
. Calling open
will open Link and display the Consent Pane view, calling exit
will close Link, and calling destroy
will clean up the iframe.
It is recommended to call Plaid.create
when initializing the view that is responsible for loading Plaid, as this will allow Plaid to pre-initialize Link, resulting in lower UI latency upon calling open
, which can increase Link conversion.
When using the React SDK, this method is called usePlaidLink
and returns an object with four values, open
, exit
, ready
, and error
. The values open
and exit
behave as described above. ready
is a passthrough for onLoad
and will be true
when Link is ready to be opened. error
is populated only if Plaid fails to load the Link JavaScript. There is no separate method to destroy Link in the React SDK, as unmount will automatically destroy the Link instance.
Note: Control whether or not your Link integration uses the Account Select view from the Dashboard.
token
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. See the /link/token/create
endpoint for a full list of configurations.onLoad
plaidLinkHandler.open()
prior to the onLoad
callback will be delayed until the module is fully loaded.receivedRedirectUri
receivedRedirectUri
is required to support OAuth authentication flows when re-launching Link on a mobile device.key
public_key
is no longer used for new implementations of Link. If your integration is still using a public_key
, see the migration guide to upgrade to using a link_token
. See the maintenance guide to troubleshoot any public_key
issues.1// The usePlaidLink hook manages Plaid Link creation2// It does not return a destroy function;3// instead, on unmount it automatically destroys the Link instance4const config: PlaidLinkOptions = {5 onSuccess: (public_token, metadata) => {}6 onExit: (err, metadata) => {}7 onEvent: (eventName, metadata) => {}8 token: 'GENERATED_LINK_TOKEN',9};1011const { open, exit, ready } = usePlaidLink(config);
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
metadata
institution
null
.name
'Wells Fargo'
institution_id
accounts
accounts
will only include selected accounts.id
account_id
name
mask
type
subtype
verification_status
pending_automatic_verification
: The Item is pending automatic verificationpending_manual_verification
: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the deposit.automatically_verified
: The Item has successfully been automatically verifiedmanually_verified
: The Item has successfully been manually verifiedverification_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.database_matched
: The Item has successfully been verified using Plaid's data sources.database_insights_pending
: The Database Insights result is pending and will be available upon Auth request.null
: Neither micro-deposit-based verification nor database verification are being used for the Item.class_type
business
or personal
account.account
accounts
instead.link_session_id
transfer_status
COMPLETE
– The transfer was completed.INCOMPLETE
– The transfer could not be completed. For help, see Troubleshooting transfers.
COMPLETE
, INCOMPLETE
1import {2 PlaidLinkOnSuccess,3 PlaidLinkOnSuccessMetadata,4} from 'react-plaid-link';56const onSuccess = useCallback<PlaidLinkOnSuccess>(7 (public_token: string, metadata: PlaidLinkOnSuccessMetadata) => {8 // log and save metadata9 // exchange public token10 fetch('//yourserver.com/exchange-public-token', {11 method: 'POST',12 headers: {13 'Content-Type': 'application/json',14 },15 body: {16 public_token,17 },18 });19 },20 [],21);
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: null14 },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. onExit
takes two arguments, a nullable error
object and a metadata
object. The metadata
parameter is always present, though some values may be null
. Note that onExit
will not be called when Link is destroyed in some other way than closing Link, such as the user hitting the browser back button or closing the browser tab on which the Link session is present.
error
error_type
error_code
error_type
has a specific set of error_codes
.error_message
display_message
null
if the error is not related to user action. This may change over time and is not safe for programmatic use.metadata
institution
null
.name
Wells Fargo
institution_id
status
requires_questions
requires_selections
requires_code
choose_device
requires_credentials
requires_account _selection
requires_oauth
institution_not_found
institution_not _supported
link_session_id
request_id
1import {2 PlaidLinkOnExit,3 PlaidLinkOnExitMetadata,4 PlaidLinkError,5} from 'react-plaid-link';67const onExit = useCallback<PlaidLinkOnExit>(8 (error: PlaidLinkError, metadata: PlaidLinkOnExitMetadata) => {9 // log and save error and metadata10 // handle invalid link token11 if (error != null && error.error_code === 'INVALID_LINK_TOKEN') {12 // generate new link token13 }14 // to handle other error codes, see https://plaid.com/docs/errors/15 },16 [],17);
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 OPEN
, LAYER_READY
, and LAYER_NOT_AVAILABLE
events will fire in real time; subsequent events will fire at the end of the Link flow, along with the onSuccess
or onExit
callback. Callback ordering is not guaranteed; onEvent
callbacks may fire before, after, or surrounding the onSuccess
or onExit
callback, and event callbacks are not guaranteed to fire in the order in which they occurred. 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 are suitable for programmatic use in your application's logic: OPEN
, EXIT
, HANDOFF
, SELECT_INSTITUTION
, ERROR
, BANK_INCOME_INSIGHTS_COMPLETED
, IDENTITY_VERIFICATION_PASS_SESSION
, IDENTITY_VERIFICATION_FAIL_SESSION
, LAYER_READY
, LAYER_NOT_AVAILABLE
. The remaining callback events are informational and subject to change and should be used for analytics and troubleshooting purposes only.
eventName
BANK_INCOME_INSIGHTS _COMPLETED
CLOSE_OAUTH
CONNECT_NEW _INSTITUTION
ERROR
error_code
metadata.FAIL_OAUTH
HANDOFF
IDENTITY_VERIFICATION _START_STEP
view_name
.IDENTITY_VERIFICATION _PASS_STEP
view_name
.IDENTITY_VERIFICATION _FAIL_STEP
view_name
.IDENTITY_VERIFICATION _PENDING_REVIEW_STEP
IDENTITY_VERIFICATION _CREATE_SESSION
IDENTITY_VERIFICATION _RESUME_SESSION
IDENTITY_VERIFICATION _PASS_SESSION
IDENTITY_VERIFICATION _FAIL_SESSION
IDENTITY_VERIFICATION _PENDING_REVIEW _SESSION
IDENTITY_VERIFICATION _OPEN_UI
IDENTITY_VERIFICATION _RESUME_UI
IDENTITY_VERIFICATION _CLOSE_UI
LAYER_NOT_AVAILABLE
LAYER_READY
open()
may now be called.MATCHED_SELECT _INSTITUTION
routing_number
was provided when calling /link/token/create
. To distinguish between the two scenarios, see metadata.match_reason
.MATCHED_SELECT_VERIFY _METHOD
OPEN
OPEN_MY_PLAID
OPEN_OAUTH
SEARCH_INSTITUTION
SELECT_AUTH_TYPE
selection
metadata to indicate the user's selection.SELECT_BRAND
SELECT_BRAND
event is only emitted for large financial institutions with multiple online banking portals.SELECT_DEGRADED _INSTITUTION
DEGRADED
health status and was shown a corresponding message.SELECT_DOWN _INSTITUTION
DOWN
health status and was shown a corresponding message.SELECT_FILTERED _INSTITUTION
SELECT_INSTITUTION
SKIP_SUBMIT_PHONE
SUBMIT_ACCOUNT_NUMBER
account_number_mask
metadata to indicate the mask of the account number the user provided.SUBMIT_CREDENTIALS
SUBMIT_DOCUMENTS
SUBMIT_DOCUMENTS_ERROR
SUBMIT_DOCUMENTS _SUCCESS
SUBMIT_MFA
SUBMIT_OTP
SUBMIT_PHONE
SUBMIT_ROUTING_NUMBER
routing_number
metadata to indicate user's routing number.TRANSITION_VIEW
TRANSITION_VIEW
event indicates that the user has moved from one view to the next.VERIFY_PHONE
VIEW_DATA_TYPES
metadata
account_number_mask
account_number_mask
is empty. Emitted by SUBMIT_ACCOUNT_NUMBER
.error_type
ERROR
, EXIT
.error_code
ERROR
, EXIT
.error_message
ERROR
, EXIT
.exit_status
EXIT
institution_id
institution_name
institution_search _query
SEARCH_INSTITUTION
.is_update_mode
OPEN
.match_reason
returning_user
or routing_number
if emitted by: MATCHED_SELECT_INSTITUTION
.
Otherwise, this will be SAVED_INSTITUTION
or AUTO_SELECT_SAVED_INSTITUTION
if emitted by: SELECT_INSTITUTION
.routing_number
SUBMIT_ROUTING_NUMBER
.mfa_type
code
, device
, questions
, selections
. Emitted by: SUBMIT_MFA
and TRANSITION_VIEW
when view_name
is MFA
view_name
TRANSITION_VIEW
.ACCEPT_TOS
CONNECTED
CONSENT
CREDENTIAL
DATA_TRANSPARENCY
DATA_TRANSPARENCY _CONSENT
DOCUMENTARY _VERIFICATION
ERROR
EXIT
INSTANT_MICRODEPOSIT _AUTHORIZED
KYC_CHECK
LOADING
MATCHED_CONSENT
MATCHED_CREDENTIAL
MATCHED_MFA
MFA
NUMBERS
NUMBERS_SELECT _INSTITUTION
OAUTH
RECAPTCHA
RISK_CHECK
SAME_DAY_MICRODEPOSIT _AUTHORIZED
SCREENING
SELECT_ACCOUNT
SELECT_AUTH_TYPE
SELECT_BRAND
SELECT_INSTITUTION
SELECT_SAVED_ACCOUNT
SELECT_SAVED _INSTITUTION
SELFIE_CHECK
SUBMIT_PHONE
UPLOAD_DOCUMENTS
VERIFY_PHONE
VERIFY_SMS
request_id
link_session_id
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
2017-09-14T14:42:19.350Z
. Emitted by: all events.selection
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
.1import {2 PlaidLinkOnEvent,3 PlaidLinkOnEventMetadata,4 PlaidLinkStableEvent,5} from 'react-plaid-link';67const onEvent = useCallback<PlaidLinkOnEvent>(8 (9 eventName: PlaidLinkStableEvent | string,10 metadata: PlaidLinkOnEventMetadata,11 ) => {12 // log eventName and metadata13 },14 [],15);
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 selection: null,15}
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 { open, exit, ready } = usePlaidLink(config);23// Open Link4if (ready) {5 open();6}
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
true
, Link will exit immediately. If false
, or the option is not provided, an exit confirmation screen may be presented to the user.1const { open, exit, ready } = usePlaidLink(config);23// Graceful exit - Link may display a confirmation screen4// depending on how far the user is in the flow5exit();
1const { open, exit, ready } = usePlaidLink(config);23// Force exit - Link exits immediately4exit({ 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.
1// On unmount usePlaidLink hook automatically destroys any2// existing link instance
submit
The submit
function is currently only used in the Layer product. It allows the client application to submit additional user-collected data to the Link flow (e.g. a user phone number).
phone_number
1const { open, exit, submit } = usePlaidLink(config);23// After collecting a user phone number...4submit({5 "phone_number": "+14155550123"6});
OAuth
Using Plaid Link with an OAuth flow requires some additional setup instructions. For details, see the OAuth Guide.
Supported browsers
Plaid officially supports Link on the latest versions of Chrome, Firefox, Safari, and Edge. Browsers are supported on Windows, Mac, Linux, iOS, and Android. Previous browser versions are also supported, as long as they are actively maintained; Plaid does not support browser versions that are no longer receiving patch updates, or that have been assigned official end of life (EOL) or end of support (EOS) status.
Ad-blocking software is not officially supported with Link web, and some ad-blockers have known to cause conflicts with Link.
Example code in Plaid Pattern
For a real-life example of using Plaid Link for React, see LaunchLink.tsx. This file illustrates the code for implementation of Plaid Link for React for the Node-based Plaid Pattern sample app.