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.

Link webview

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

create
isWebviewboolean
Set to true, to trigger the Webview integration.
tokenstring
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 flow. See the /link/token/create endpoint for a full list of configurations.
receivedRedirectUristring
A 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.
keydeprecatedstring
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.
1https://cdn.plaid.com/link/v2/stable/link.html
2  ?isWebview=true
3  &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:

connected
public_tokenstring
Displayed once a user has successfully linked their Item.
institution_namestring
The full institution name, such as 'Wells Fargo'
institution_idstring
The Plaid institution identifier
accountsobject
A 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.
idstring
The Plaid account_id
namestring
The official account name
masknullable string
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, it may also not match the mask that the bank displays to the user.
typestring
The account type. See the Account schema for a full list of possible values
subtypestring
The account subtype. See the Account schema for a full list of possible values
verification_statusstring
When all Auth features are enabled by initializing Link with the user object, the accounts object includes an Item's verification_status. See Auth accounts for a full list of possible values.
transfer_statusnullable string
The status of a transfer. Returned only when Transfer UI is implemented.
  • COMPLETE – The transfer was completed.
  • INCOMPLETE – The transfer could not be completed. For help, see Troubleshooting transfers.


Possible values: COMPLETE, INCOMPLETE
link_session_idstring
A 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://connected
2  ?public_token=public-sandbox-fb7cca4a-82e6-4707
3  &institution_id=ins_3
4  &institution_name=Chase
5  &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:

exit
statusstring
The point at which the user exited the Link flow. One of the following values.
requires_questions
User prompted to answer security questions
requires_selections
User prompted to answer multiple choice question(s)
requires_code
User prompted to provide a one-time passcode
choose_device
User prompted to select a device on which to receive a one-time passcode
requires_credentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution
requires_account_selection
User prompted to select one or more financial accounts to share
requires_oauth
User prompted to enter an OAuth flow
institution_not_found
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
error_typeString
A broad categorization of the error.
error_codeString
The particular error code. Each error_type has a specific set of error_codes.
error_messageString
A developer-friendly representation of the error code.
display_messagenullable String
A 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_namestring
The full institution name, such as Wells Fargo
institution_idstring
The Plaid institution identifier
link_session_idstring
A 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_idstring
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.
1plaidlink://exit
2  ?status=requires_credentials
3  &error_type=ITEM_ERROR
4  &error_code=ITEM_LOGIN_REQUIRED
5  &error_display_message=The%20credentials%20were%20not%20correct.%20Please%20try%20again.
6  &error_message=the%20credentials%20were%20not%20correct
7  &institution_id=ins_3
8  &institution_name=Chase
9  &link_session_id=79e772be-547d-4c9c-8b76-4ac4ed4c441a
10  &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
event_namestring
A string representing the event that has just occurred in the Link flow.
BANK_INCOME_INSIGHTS_COMPLETED
The user has completed the Assets and Bank Income Insights flow.
CLOSE_OAUTH
The user closed the third-party website or mobile app without completing the OAuth flow.
ERROR
A recoverable error occurred in the Link flow, see the error_code metadata.
EXIT
The user has exited without completing the Link flow and the onExit callback is fired.
FAIL_OAUTH
The user encountered an error while completing the third-party's OAuth login flow.
HANDOFF
The user has exited Link after successfully linking an Item.
MATCHED_SELECT_INSTITUTION
The user selected an institution that was presented as a matched institution.
MATCHED_SELECT_VERIFY_METHOD
The user selected a verification method for a matched institution.
OPEN
The user has opened Link.
OPEN_MY_PLAID
The user has opened my.plaid.com. This event is only sent when Link is initialized with Assets as a product
OPEN_OAUTH
The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.
SEARCH_INSTITUTION
The user has searched for an institution.
SELECT_BRAND
The user selected a brand, e.g. Bank of America. The SELECT_BRAND event is only emitted for large financial institutions with multiple online banking portals.
SELECT_DEGRADED_INSTITUTION
The user selected an instititon with a DEGRADED health status and were shown a corresponding message.
SELECT_DOWN_INSTITUTION
The user selected an instititon with a DOWN health status and were shown a corresponding message.
SELECT_INSTITUTION
The user selected an institution.
SUBMIT_CREDENTIALS
The user has submitted credentials.
SUBMIT_DOCUMENTS
The user is being prompted to submit documents for an Income verification flow.
SUBMIT_DOCUMENTS_ERROR
The user encountered an error when submitting documents for an Income verification flow.
SUBMIT_DOCUMENTS_SUCCESS
The user has successfully submitted documents for an Income verification flow.
SUBMIT_MFA
The user has submitted MFA.
TRANSITION_VIEW
The TRANSITION_VIEW event indicates that the user has moved from one view to the next.
error_typenullable string
The error type that the user encountered. Emitted by: ERROR, EXIT.
error_codenullable string
The error code that the user encountered. Emitted by ERROR, EXIT.
error_messagenullable string
The error message that the user encountered. Emitted by: ERROR, EXIT.
exit_statusnullable string
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT
institution_idnullable string
The ID of the selected institution. Emitted by: all events.
institution_namenullable string
The name of the selected institution. Emitted by: all events.
institution_search_querynullable string
The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
match_reasonnullable string
The reason this institution was matched, which will be either returning_user or routing_number. Emitted by: MATCHED_SELECT_INSTITUTION
mfa_typenullable string
If 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_namenullable string
The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.
CONNECTED
The user has connected their account.
CONSENT
We ask the user to consent to the privacy policy.
CREDENTIAL
Asking the user for their account credentials.
ERROR
An error has occurred.
EXIT
Confirming if the user wishes to close Link.
LOADING
Link is making a request to our servers.
MATCHED_CONSENT
We ask the matched user to consent to the privacy policy and SMS terms.
MATCHED_CREDENTIAL
We ask the matched user for their account credentials to a matched institution.
MATCHED_MFA
We ask the matched user for MFA authentication to verify their identity.
MFA
The user is asked by the institution for additional MFA authentication.
NUMBERS
The user is asked to insert their account and routing numbers.
OAUTH
The user is informed they will authenticate with the financial institution via OAuth.
RECAPTCHA
The user was presented with a Google reCAPTCHA to verify they are human.
SELECT_ACCOUNT
We ask the user to choose an account.
SELECT_BRAND
The user selected a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.
SELECT_INSTITUTION
We ask the user to choose their institution.
request_idstring
The 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_idstring
The 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.
timestampstring
An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.
selectionnullable string
Either 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://event
2  &event_name=SELECT_INSTITUTION
3  ?error_type=ITEM_ERROR
4  &error_code=ITEM_LOGIN_REQUIRED
5  &error_message=the%20credentials%20were%20not%20correct
6  &exit_status
7  &institution_id=ins_55
8  &institution_name=HSBC
9  &institution_search_query=h
10  &mfa_type
11  &view_name=ERROR
12  &request_id
13  &link_session_id=821f45a8-854a-4dbb-8e5f-73f75350e7e7
14  &timestamp=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.