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.
1<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
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 https://cdn.plaid.com/link/v2/stable/link-initialize.js3frame-src https://cdn.plaid.com/4connect-src https://production.plaid.com/
If using Sandbox or Development instead of production, make sure to update the connect-src
directive to point to the appropriate server (https://sandbox.plaid.com
or https://development.plaid.com
).
Create
Plaid.create
accepts one argument, a configuration Object
, and returns an Object
with three functions, open
, exit
, and destroy
. Calling open
will display the Consent Pane view, calling exit
will close Link, and calling destroy
will clean up the iframe.
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 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.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 //required for OAuth; if not using OAuth, set to null or omit:10 receivedRedirectUri: window.location.href,11};1213const { 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 two amounts.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.null
: micro-deposit-based verification is not 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
wallet
name
'MetaMask'
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: ''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
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
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 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
, IDENTITY_VERIFICATION_PASS_SESSION
, IDENTITY_VERIFICATION_FAIL_SESSION
. The remaining callback events are informational and subject to change.
eventName
BANK_INCOME_INSIGHTS _COMPLETED
CLOSE_OAUTH
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 _OPEN_UI
IDENTITY_VERIFICATION _RESUME_UI
IDENTITY_VERIFICATION _CLOSE_UI
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_INSTITUTION
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_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.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
.match_reason
returning_user
or routing_number
. Emitted by: MATCHED_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
KYC_CHECK
LOADING
MATCHED_CONSENT
MATCHED_CREDENTIAL
MATCHED_MFA
MFA
NUMBERS
OAUTH
RECAPTCHA
RISK_CHECK
SCREENING
SELECT_ACCOUNT
SELECT_AUTH_TYPE
SELECT_BRAND
SELECT_INSTITUTION
SELFIE_CHECK
UPLOAD_DOCUMENTS
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
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 current and previous versions of Chrome, Firefox, and Safari, as well as Internet Explorer 11 and the current version of Microsoft Edge. Browsers are supported on Windows, Mac, Linux, iOS (Safari), and Android (Chrome).
Ad-blocking software is not 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.