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:

Link Webview initialization URL
1
https://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.

HTTP redirect scheme
1
plaidlink://

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 and using one or more European country codes.

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.

Create example
1
2
3
4
https://cdn.plaid.com/link/v2/stable/link.html
  ?isWebview=true
  &token="GENERATED_LINK_TOKEN"
  &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 Select Account is enabled via the developer dashboard, accounts will only include selected accounts.

idstring

The Plaid account_id

namestring

The official account name

maskstring

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.

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.

Connected event example
1
2
3
4
5
6
plaidlink://connected
  ?public_token=public-sandbox-fb7cca4a-82e6-4707
  &institution_id=ins_3
  &institution_name=Chase
  &accounts='[{"name":"Plaid Savings","id":"QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK", "mask": "0000", "type": "depository", "subtype": "checking"}]'
  &link_session_id=79e772be-547d-4c9c-8b76-4ac4ed4c441a

accounts schema example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
accounts= [
  {
    id: 'ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy',
    name: 'Plaid Checking',
    mask: '0000',
    type: 'depository',
    subtype: 'checking',
    verification_status: ''
  },
  {
    id: '9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4',
    name: 'Plaid Saving',
    mask: '1111',
    type: 'depository',
    subtype: 'savings'
  }
  ...
]

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_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_messageString

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.

onExit example
1
2
3
4
5
6
7
8
9
10
plaidlink://exit
  ?status=requires_credentials
  &error_type=ITEM_ERROR
  &error_code=ITEM_LOGIN_REQUIRED
  &error_display_message=The%20credentials%20were%20not%20correct.%20Please%20try%20again.
  &error_message=the%20credentials%20were%20not%20correct
  &institution_id=ins_3
  &institution_name=Chase
  &link_session_id=79e772be-547d-4c9c-8b76-4ac4ed4c441a
  &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.

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 brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.

SELECT_INSTITUTION

The user selected an institution.

SUBMIT_CREDENTIALS

The user has submitted credentials.

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_typestring

The error type that the user encountered. Emitted by: ERROR, EXIT.

error_codestring

The error code that the user encountered. Emitted by ERROR, EXIT.

error_messagestring

The error message that the user encountered. Emitted by: ERROR, EXIT.

exit_statusstring

The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT

institution_idstring

The ID of the selected institution. Emitted by: all events.

institution_namestring

The name of the selected institution. Emitted by: all events.

institution_search_querystring

The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.

mfa_typestring

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_namestring

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.

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

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.

selectionstring

The verification method for a matched institution selected by the user. Possible values are phoneotp, password. Emitted by: MATCHED_SELECT_VERIFY_METHOD.

event example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
plaidlink://event
  &event_name=SELECT_INSTITUTION
  ?error_type=ITEM_ERROR
  &error_code=ITEM_LOGIN_REQUIRED
  &error_message=the%20credentials%20were%20not%20correct
  &exit_status
  &institution_id=ins_55
  &institution_name=HSBC
  &institution_search_query=h
  &mfa_type
  &view_name=ERROR
  &request_id
  &link_session_id=821f45a8-854a-4dbb-8e5f-73f75350e7e7
  &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.