Link Web SDK
Reference for integrating with the Link JavaScript SDK and React SDK
Prefer to learn with code examples? A GitHub repo showing a working example Link implementation is available for this topic.
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>
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 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. |
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. |
receivedRedirectUri string A receivedRedirectUri is required to support OAuth authentication flows when re-launching Link on a mobile device. |
key deprecatedstring The 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 string Displayed once a user has successfully linked their Item. | |||||||||||||
metadata object Displayed once a user has successfully linked their Item.
|
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 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.
|
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
. 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.
|
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}
onResult
The onResult
callback is called during the Link flow to return incremental results for Bank Income. It takes one argument, an incremental_result
object.
item_add_result nullable object Information about an Item successfully linked by a user. Currently, item_add_result will not be null ; it is nullable to support future use cases for onResult in which item_add_result may not be relevant
|
1// React library coming soon
1{2 "item_add_result": {3 "public_token": "public-production-43eea6ef-1ed4-48f7-9d10-e330aceb2de0",4 "metadata": {5 "link_session_id": "abcd-efgh"6 "institution": {7 "name": "Island Federal Credit Union"8 "institution_id": "ins_116369",9 }10 }11 }12}
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 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 { 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.