Link - Webview | Plaid Docs

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

Set to true, to trigger the Webview integration.

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.

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.

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 the user completes the Link flow. The following information is available from the querystring event:

connected

Displayed once a user has successfully linked their Item.

The full institution name, such as 'Wells Fargo'

The Plaid institution identifier

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.

The Plaid account_id

The official account name

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.

The account type. See the Account schema for a full list of possible values

The account subtype. See the Account schema for a full list of possible values

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.

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 the user exits the Link flow or if an error occurs during Link initialization. The following information is available from the querystring:

exit

The point at which the user exited the Link flow. One of the following values.

User prompted to answer security questions

User prompted to answer multiple choice question(s)

User prompted to provide a one-time passcode

User prompted to select a device on which to receive a one-time passcode

User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution

User prompted to enter an OAuth flow

User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution

A broad categorization of the error.

The particular error code. Each error_type has a specific set of error_codes.

A developer-friendly representation of the error code.

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.

The full institution name, such as Wells Fargo

The Plaid institution identifier

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.

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

A string representing the event that has just occurred in the Link flow.

The user closed the third-party website or mobile app without completing the OAuth flow.

A recoverable error occurred in the Link flow, see the error_code metadata.

The user has exited without completing the Link flow and the onExit callback is fired.

The user encountered an error while completing the third-party's OAuth login flow.

The user has completed the Link flow and the onSuccess callback is fired.

The user selected an institution that was presented as a matched institution.

The user selected a verification method for a matched institution.

The user has opened Link.

The user has opened my.plaid.com. This event is only sent when Link is initialized with Assets as a product

The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.

The user has searched for an institution.

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.

The user selected an institution.

The user has submitted credentials.

The user has submitted MFA.

The TRANSITION_VIEW event indicates that the user has moved from one view to the next.

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

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

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

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

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

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

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

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

The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.

The user has connected their account.

We ask the user to consent to the privacy policy.

Asking the user for their account credentials.

An error has occurred.

Confirming if the user wishes to close Link.

Link is making a request to our servers.

We ask the matched user to consent to the privacy policy and SMS terms.

We ask the matched user for their account credentials to a matched institution.

We ask the matched user for MFA authentication to verify their identity.

The user is asked by the institution for additional MFA authentication.

The user is asked to insert their account and routing numbers.

The user was presented with a Google reCAPTCHA to verify they are human.

We ask the user to choose an account.

We ask the user to choose their institution.

The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.

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.

An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.

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.

Link Webview SDK

Reference for integrating with the Link Webview JavaScript SDK

Overview

Installation

Communication between Link and your app

Create

connected

exit

event

OAuth

Supported platforms