Plaid logo
Docs
ALL DOCS

Link

  • Overview
Platforms
  • Web
  • iOS
  • Android
  • React Native
  • Hosted Link
Core Link functionality
  • OAuth guide
  • Update mode
  • Preventing duplicate Items
  • Data Transparency Messaging migration
  • Returning user experience
Additional Link modes
  • Embedded Link
  • Multi-Item Link
  • Link Recovery (beta)
  • Modular Link (UK/EU only)
Optimizing Link
  • Link analytics and tracking
  • Optimizing Link conversion
  • Pre-Link messaging
  • Customizing Link
  • Choosing when to initialize products
Errors and troubleshooting
  • Troubleshooting
  • Handling an invalid Link Token
  • Institution status in Link
Legacy flows
  • Legacy public key integrations
  • Link Token migration guide
  • Webview integrations
Plaid logo
Docs
Close search modal
Ask Bill!
Ask Bill!
Hi! I'm Bill! You can ask me all about the Plaid API. Try asking questions like:
    Note: Bill isn't perfect. He's just a robot platypus that reads our docs for fun. You should treat his answers with the same healthy skepticism you might treat any other answer on the internet. This chat may be logged for quality and training purposes. Please don't send Bill any PII -- he's scared of intimacy. All chats with Bill are subject to Plaid's Privacy Policy.
    Plaid.com
    Log in
    Get API Keys
    Open nav

    Link Webview SDK

    Reference for integrating with the Link Webview JavaScript SDK

    Using webviews to present Link is deprecated. If you're currently integrating this way, we recommend migrating to Hosted Link or one Plaid's official SDKs for Android, iOS, and React Native.

    All Webview-based integrations need to extend the Webview handler for redirects in order to support connections to Chase. This can be accomplished with code samples for iOS and Android. For more details, see Extending webview instances to support certain institutions in the OAuth Guide and the in-process Webview deprecation notice. Webview-based integrations that do not extend the Webview handler are not supported by Chase and may be blocked by Chase in the future.

    If your integration does not connect to Chase (for example, because you use only Identity Verification, Document Income, or Payroll Income, or you do not support end users in the US) you may ignore this warning.

    =*=*=*=

    Overview

    To integrate and use Plaid Link inside a Webview, we recommend starting with one of our sample Webview apps:

    • iOS WKWebView
    • Android Webview

    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
    isWebview
    booleanboolean
    Set to true, to trigger the Webview integration.
    token
    stringstring
    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. See the /link/token/create endpoint for a full list of configurations.
    receivedRedirectUri
    stringstring
    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.
    key
    deprecatedstringdeprecated, string
    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 completes Link. The following information is available from the querystring event:

    connected
    public_token
    stringstring
    Displayed once a user has successfully completed Link. If using Identity Verification or Beacon, this field will be null. If using Document Income or Payroll Income, the public_token will be returned, but is not used.
    institution_name
    stringstring
    The full institution name, such as 'Wells Fargo'
    institution_id
    stringstring
    The Plaid institution identifier
    accounts
    objectobject
    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.
    _id
    stringstring
    The Plaid account_id
    meta
    objectobject
    The account metadata
    name
    stringstring
    The official account name
    number
    nullablestringnullable, 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.
    type
    stringstring
    The account type. See the Account schema for a full list of possible values
    subtype
    stringstring
    The account subtype. See the Account schema for a full list of possible values
    verification_status
    stringstring
    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.
    class_type
    nullablestringnullable, string
    If micro-deposit verification is being used, indicates whether the account being verified is a business or personal account.
    transfer_status
    nullablestringnullable, 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_id
    stringstring
    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='[{"_id":"QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK", "meta": {"name":"Plaid Savings", "number": "0000"}, "subtype": "checking", "type": "depository" }]'
    6 &link_session_id=79e772be-547d-4c9c-8b76-4ac4ed4c441a
    1"accounts": [
    2 {
    3 "_id": "ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy",
    4 "meta": {
    5 "name": "Plaid Checking",
    6 "number": "0000",
    7 },
    8 "type": "depository",
    9 "subtype": "checking",
    10 "verification_status": null
    11 },
    12 {
    13 "_id": "9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4",
    14 "meta": {
    15 "name": "Plaid Saving",
    16 "number": "1111"
    17 },
    18 "type": "depository",
    19 "subtype": "savings"
    20 }
    21 ...
    22]
    =*=*=*=

    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. Note that on Android devices, an exit event will not be sent if the user exits Link through a system action, such as hitting the browser back button. The following information is available from the querystring:

    exit
    status
    stringstring
    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 on the institution selection pane. Typically this occurs after the user unsuccessfully (no results returned) searched for a financial institution. Note that this status does not necessarily indicate that the user was unable to find their institution, as it is used for all user exits that occur from the institution selection pane, regardless of other user behavior.
    institution_not_supported
    User exited the Link flow after discovering their selected institution is no longer supported by Plaid
    error_type
    StringString
    A broad categorization of the error.
    error_code
    StringString
    The particular error code. Each error_type has a specific set of error_codes.
    error_message
    StringString
    A developer-friendly representation of the error code.
    display_message
    nullableStringnullable, 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_name
    stringstring
    The full institution name, such as Wells Fargo
    institution_id
    stringstring
    The Plaid institution identifier
    link_session_id
    stringstring
    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_id
    stringstring
    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_name
    stringstring
    A string representing the event that has just occurred in the Link flow.
    AUTO_SUBMIT_PHONE
    The user was automatically sent an OTP code without a UI prompt. This event can only occur if the user's phone phone number was provided to Link via the /link/token/create call and the user has previously consented to receive OTP codes from Plaid.
    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.
    CONNECT_NEW_INSTITUTION
    The user has chosen to link a new institution instead of linking a saved institution. This event is only emitted in the Link Returning User Experience 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 exit 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.
    IDENTITY_MATCH_FAILED
    An Identity Match check configured via the Account Verification Dashboard failed the Identity Match rules and did not detect a match.
    IDENTITY_MATCH_PASSED
    An Identity Match check configured via the Account Verification Dashboard passed the Identity Match rules and detected a match.
    INSTANT_MICRODEPOSIT_AUTHORIZED
    The user has authorized an instant micro-deposit to be sent to their account over the RTP or FedNow network with a 3-letter code to verify their account.
    MATCHED_SELECT_INSTITUTION
    The user selected an institution that was presented as a matched institution. This event can be emitted if Embedded Institution Search is being used, if the institution was surfaced as a matched institution likely to have been linked to Plaid by a returning user, or if the institution's routing_number was provided when calling /link/token/create. For details on which scenario is triggering the event, see metadata.matchReason.
    MATCHED_SELECT_VERIFY_METHOD
    deprecateddeprecated,
    The user selected a verification method for a matched institution. This event is emitted only during the legacy version of the Returning User Experience flow.
    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.
    SAME_DAY_MICRODEPOSIT_AUTHORIZED
    The user has authorized a same day micro-deposit to be sent to their account over the ACH network with a 3-letter code to verify their account.
    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 institution with a DEGRADED health status and was shown a corresponding message.
    SELECT_DOWN_INSTITUTION
    The user selected an institution with a DOWN health status and was shown a corresponding message.
    SELECT_FILTERED_INSTITUTION
    The user selected an institution Plaid does not support all requested products for and was shown a corresponding message.
    SELECT_INSTITUTION
    The user selected an institution.
    SKIP_SUBMIT_PHONE
    The user has opted to not provide their phone number to Plaid. This event is only emitted in the Link Returning User Experience flow.
    SUBMIT_ACCOUNT_NUMBER
    The user has submitted an account number. This event emits the account_number_mask metadata to indicate the mask of the account number the user provided.
    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.
    SUBMIT_OTP
    The user has submitted an OTP code during the phone number verification flow. This event is only emitted in the Link Returning User Experience flow.
    SUBMIT_PHONE
    The user has submitted their phone number. This event is only emitted in the Link Returning User Experience flow.
    SUBMIT_ROUTING_NUMBER
    The user has submitted a routing number. This event emits the routing_number metadata to indicate user's routing number.
    TRANSITION_VIEW
    The TRANSITION_VIEW event indicates that the user has moved from one view to the next.
    VERIFY_PHONE
    The user has successfully verified their phone number. This event is only emitted in the Link Returning User Experience flow.
    VIEW_DATA_TYPES
    The user has viewed data types on the data transparency consent pane.
    error_type
    nullablestringnullable, string
    The error type that the user encountered. Emitted by: ERROR, EXIT.
    error_code
    nullablestringnullable, string
    The error code that the user encountered. Emitted by ERROR, EXIT.
    error_message
    nullablestringnullable, string
    The error message that the user encountered. Emitted by: ERROR, EXIT.
    exit_status
    nullablestringnullable, string
    The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT
    institution_id
    nullablestringnullable, string
    The ID of the selected institution. Emitted by: all events.
    institution_name
    nullablestringnullable, string
    The name of the selected institution. Emitted by: all events.
    institution_search_query
    nullablestringnullable, string
    The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
    is_update_mode
    nullablestringnullable, string
    Indicates if the current Link session is an update mode session. Emitted by: OPEN.
    match_reason
    nullablestringnullable, string
    The reason this institution was matched. This will be either returning_user or routing_number if emitted by: MATCHED_SELECT_INSTITUTION. Otherwise, this will be SAVED_INSTITUTION or AUTO_SELECT_SAVED_INSTITUTION if emitted by: SELECT_INSTITUTION.
    mfa_type
    nullablestringnullable, 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_name
    nullablestringnullable, string
    The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.
    ACCEPT_TOS
    The view showing Terms of Service in the identity verification flow.
    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.
    DATA_TRANSPARENCY
    We disclose the data types being shared.
    DATA_TRANSPARENCY_CONSENT
    We ask the user to consent to the privacy policy and disclose data types being shared.
    DOCUMENTARY_VERIFICATION
    The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).
    ERROR
    An error has occurred.
    EXIT
    Confirming if the user wishes to close Link.
    INSTANT_MICRODEPOSIT_AUTHORIZED
    The user has authorized an instant micro-deposit to be sent to their account over the RTP or FedNow network with a 3-letter code to verify their account.
    KYC_CHECK
    The view representing the "know your customer" step in the identity verification flow.
    LOADING
    Link is making a request to our servers.
    MATCHED_CONSENT
    deprecateddeprecated,
    We ask the matched user to consent to the privacy policy and SMS terms. Used only in the legacy version of the Returning User Experience flow.
    MATCHED_CREDENTIAL
    deprecateddeprecated,
    We ask the matched user for their account credentials to a matched institution. Used only in the legacy version of the Returning User Experience flow.
    MATCHED_MFA
    deprecateddeprecated,
    We ask the matched user for MFA authentication to verify their identity. Used only in the legacy version of the Returning User Experience flow.
    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.
    RISK_CHECK
    The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).
    SAME_DAY_MICRODEPOSIT_AUTHORIZED
    The user has authorized a same day micro-deposit to be sent to their account over the ACH network with a 3-letter code to verify their account.
    SCREENING
    The watchlist screening step in the identity verification flow.
    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.
    SELECT_SAVED_ACCOUNT
    The user is asked to select their saved accounts and/or new accounts for linking in the Link Returning User Experience flow.
    SELECT_SAVED_INSTITUTION
    The user is asked to pick a saved institution or link a new one in the Link Returning User Experience flow.
    SELFIE_CHECK
    The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.
    SUBMIT_PHONE
    The user is asked for their phone number in the Link Returning User Experience flow.
    VERIFY_PHONE
    The user is asked to verify their phone in the Link Returning User Experience flow.
    VERIFY_SMS
    The SMS verification step in the identity verification flow.
    request_id
    stringstring
    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_id
    stringstring
    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.
    timestamp
    stringstring
    An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.
    selection
    nullablestringnullable, 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.

    Was this helpful?
    Developer community
    GitHub
    GitHub
    Stack Overflow
    Stack Overflow
    YouTube
    YouTube
    Discord
    Discord