Link Webview SDK
Reference for integrating with the Link Webview JavaScript SDK
Plaid does not recommend the use of webviews for new integrations. Plaid's SDKs for Android, iOS, and React Native provide the easiest and best way to build a mobile Plaid experience and are recommended for all developers.
Overview
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 booleanSet to true , to trigger the Webview integration. |
token stringSpecify 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 flow. See the /link/token/create endpoint for a full list of configurations. |
receivedRedirectUri stringA receivedRedirectUri is required to support OAuth authentication flows when re-launching Link on a mobile device. Note that any unsafe ASCII characters in the receivedRedirectUri in the webview query string must be URL-encoded. |
key deprecatedstringThe 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. |
1https://cdn.plaid.com/link/v2/stable/link.html2 ?isWebview=true3 &token="GENERATED_LINK_TOKEN"4 &receivedRedirectUri=
connected
The connected
event is analogous to the onSuccess
callback in Link Web and is sent when a user successfully links an Item. The following information is available from the querystring event:
public_token stringDisplayed once a user has successfully linked their Item. | ||||||
institution_name stringThe full institution name, such as 'Wells Fargo' | ||||||
institution_id stringThe Plaid institution identifier | ||||||
accounts objectA JSON-stringified representation of the account(s) attached to the connected Item. If Account Select is enabled via the developer dashboard, accounts will only include selected accounts.
| ||||||
transfer_status nullable stringThe status of a transfer. Returned only when Transfer UI is implemented.
Possible values: COMPLETE , INCOMPLETE | ||||||
link_session_id stringA 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. |
1plaidlink://connected2 ?public_token=public-sandbox-fb7cca4a-82e6-47073 &institution_id=ins_34 &institution_name=Chase5 &accounts='[{"name":"Plaid Savings","id":"QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK", "mask": "0000", "type": "depository", "subtype": "checking"}]'6 &link_session_id=79e772be-547d-4c9c-8b76-4ac4ed4c441a
1accounts= [2 {3 id: 'ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy',4 name: 'Plaid Checking',5 mask: '0000',6 type: 'depository',7 subtype: 'checking',8 verification_status: ''9 },10 {11 id: '9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4',12 name: 'Plaid Saving',13 mask: '1111',14 type: 'depository',15 subtype: 'savings'16 }17 ...18]
exit
The exit
event is analogous to the onExit
callback and is sent when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The following information is available from the querystring:
status stringThe point at which the user exited the Link flow. One of the following values.
| ||||||||
error_type StringA broad categorization of the error. | ||||||||
error_code StringThe particular error code. Each error_type has a specific set of error_codes . | ||||||||
error_message StringA developer-friendly representation of the error code. | ||||||||
display_message nullable StringA 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. | ||||||||
institution_name stringThe full institution name, such as Wells Fargo | ||||||||
institution_id stringThe Plaid institution identifier | ||||||||
link_session_id stringA 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 stringThe request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. |
1plaidlink://exit2 ?status=requires_credentials3 &error_type=ITEM_ERROR4 &error_code=ITEM_LOGIN_REQUIRED5 &error_display_message=The%20credentials%20were%20not%20correct.%20Please%20try%20again.6 &error_message=the%20credentials%20were%20not%20correct7 &institution_id=ins_38 &institution_name=Chase9 &link_session_id=79e772be-547d-4c9c-8b76-4ac4ed4c441a10 &request_id=m8MDnv9okwxFNBV
event
The event
message is analogous to the Link Web onEvent
callback and is called as the user moves through the Link flow. The querystring will always contain all possible keys, though not all keys will have values. The event_name
will dictate which keys are populated.
event_name stringA string representing the event that has just occurred in the Link flow.
| ||||||||||||||||||||||
error_type nullable stringThe error type that the user encountered. Emitted by: ERROR , EXIT . | ||||||||||||||||||||||
error_code nullable stringThe error code that the user encountered. Emitted by ERROR , EXIT . | ||||||||||||||||||||||
error_message nullable stringThe error message that the user encountered. Emitted by: ERROR , EXIT . | ||||||||||||||||||||||
exit_status nullable stringThe status key indicates the point at which the user exited the Link flow. Emitted by: EXIT | ||||||||||||||||||||||
institution_id nullable stringThe ID of the selected institution. Emitted by: all events. | ||||||||||||||||||||||
institution_name nullable stringThe name of the selected institution. Emitted by: all events. | ||||||||||||||||||||||
institution_search_query nullable stringThe query used to search for institutions. Emitted by: SEARCH_INSTITUTION . | ||||||||||||||||||||||
match_reason nullable stringThe reason this institution was matched, which will be either returning_user or routing_number . Emitted by: MATCHED_SELECT_INSTITUTION | ||||||||||||||||||||||
mfa_type nullable stringIf 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 stringThe name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW .
| ||||||||||||||||||||||
request_id stringThe 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 stringThe 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 stringAn ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z . Emitted by: all events. | ||||||||||||||||||||||
selection nullable stringEither the verification method for a matched institution selected by the user or the Flexible Auth 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 Flexible Auth flow, then possible values are flow_type_manual or flow_type_instant . Emitted by: MATCHED_SELECT_VERIFY_METHOD and SELECT_AUTH_TYPE . |
1plaidlink://event2 &event_name=SELECT_INSTITUTION3 ?error_type=ITEM_ERROR4 &error_code=ITEM_LOGIN_REQUIRED5 &error_message=the%20credentials%20were%20not%20correct6 &exit_status7 &institution_id=ins_558 &institution_name=HSBC9 &institution_search_query=h10 &mfa_type11 &view_name=ERROR12 &request_id13 &link_session_id=821f45a8-854a-4dbb-8e5f-73f75350e7e714 ×tamp=2018-10-05T15%3A22%3A50.542Z
OAuth
Using Plaid Link with an OAuth flow requires some additional setup instructions. For details, see the OAuth Guide.
Supported platforms
Plaid officially supports WKWebView on iOS 10 or later and Chrome WebView on Android 4.4 or later.