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
  • Optimizing Link conversion
  • Link analytics and tracking
  • 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 Embedded Institution Search

    Enhance conversion by embedding institution search directly into your app

    With Embedded Institution Search (also known as Embedded Link), you can provide a more seamless transition to the account connectivity experience. For payment experiences in particular, embedding institution search can help guide users to choosing their bank account as a payment method.

    Embedded Institution Search and the Auth Database Auth) are both designed to increase adoption of ACH payment methods and are frequently used together. Embedded Institution Search is also fully compatible with other Auth flows, including micro-deposit based flows and Database Auth.

    It is highly recommended to use Embedded Institution Search for Link to increase uptake of pay-by-bank if your use case involves a pay-by-bank payments flow where the end user can choose between paying via a credit card and paying via a bank account. If your use case is an account opening or funding flow that requires the customer to use a bank account, or has a surcharge for credit card use, use the standard Link experience instead.

    In order to realize the benefits of Embedded Institution Search, you must show it by default when the payments view loads, without requiring the user to first select 'Pay by bank'. If you cannot do this, use the standard Link experience instead.

    Embedded Institution Search can be used with the following products: Auth, Identity, Balance, Signal, Transfer, Transactions, Assets, and Liabilities.

    Embedded Institution Search is not compatible with Multi-Item Link.

    For recommendations on how to improve the uptake of pay-by-bank and optimize your Embedded Institution Search UX, see Increasing Pay-by-bank adoption.

    Institution Search user experience

    The user will be able to select from a set of institution logos. You can customize which logos will be displayed via the Plaid Dashboard. If a user selects an institution, they will be taken to Link to connect their account.

    Example Embedded Institution Search Desktop experience screenshot.
    Example of Embedded Institution Search on Desktop
    Example Embedded Institution Search flow on mobile
    Example of Embedded Institution Search flow on mobile when user selects an institution

    If the user's institution is not one of the featured institutions, they can search for their institution using the search bar.

    Example Embedded Institution Search search bar experience.
    Example of searching for an institution in Embedded Institution Search on desktop

    Integration steps

    Embedded Institution Search is available for all supported integration modes except webviews and Hosted Link. Embedded Institution Search cannot be rendered inside an iFrame.

    Before integrating, make sure you are using a version of the SDK that supports Embedded Institution Search.

    PlatformMinimum SDK version required
    Android3.14.0
    iOS4.5.0
    React Native10.6.0
    React web3.5.1
    JavaScript webN/A (all customers are on the latest version)
    1. Create a Link token as normal, using /link/token/create; no special parameters are required when making this call to enable Embedded Institution Search. The 'Connect Manually' button rendering is configured with the auth_type_select_enabled boolean in the auth object.
    2. Create an embedded view. This should be done before it will be displayed in your app, to minimize latency. Plaid will track when this view is requested and activate the Embedded Search UI. If you are using iOS, call createEmbeddedView, which will return a Result containing a UIView. Once you have the UIView, add it to your ViewController's view. If you are using the web SDK, call Plaid.createEmbedded instead of Plaid.create to open Link. For other platforms, you will create the view as normal.
    3. Lay out the view Plaid returns from the configuration. If you are migrating to Embedded Institution Search from traditional Link, delete your old Link presentation in favor of this new one.
    Select group for content switcher
    1private func setupEmbeddedSearchView(token: String) {
    2
    3 // Create a configuration like normal.
    4 var configuration = LinkTokenConfiguration(
    5 token: token,
    6 onSuccess: { success in
    7 print("success: \(success)")
    8 }
    9 )
    10
    11 configuration.onEvent = { event in
    12 print("Event: \(event)")
    13 }
    14
    15 configuration.onExit = { exit in
    16 print("Exit: \(exit)")
    17 }
    18
    19 // Create a handler with your configuration like normal.
    20 let handlerResult = Plaid.create(configuration)
    21 switch handlerResult {
    22 case .success(let handler):
    23
    24 // Save a reference to your handler.
    25 self.handler = handler
    26
    27 // Create an embedded view.
    28 let embeddedSearchView = handler.createEmbeddedView(presentUsing: .viewController(self))
    29
    30 // Layout this view
    31 embeddedSearchView.translatesAutoresizingMaskIntoConstraints = false
    32 view.addSubview(embeddedSearchView)
    33
    34 NSLayoutConstraint.activate([
    35 embeddedSearchView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor, constant: 8),
    36 embeddedSearchView.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 25),
    37 embeddedSearchView.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -25),
    38 embeddedSearchView.heightAnchor.constraint(equalToConstant: 360),
    39 ])
    40
    41
    42 case .failure(let error):
    43 // Error creating handler. Handle like normal.
    44 fatalError("\(error)")
    45 }
    46 }
    1// Register a callback for an Activity Result like normal (must be done from an Activity)
    2 private val linkAccountToPlaid =
    3 registerForActivityResult(OpenPlaidLink()) { result ->
    4 when (result) {
    5 is LinkSuccess -> /* handle LinkSuccess */
    6 is LinkExit -> /* handle LinkExit (from LinkActivity) */
    7 }
    8 }
    9
    10// Create a linkTokenConfiguration like normal
    11val linkTokenConfiguration = LinkTokenConfiguration.Builder().token(token).build()
    12
    13// Create the view with a trailing lambda for handling LinkExits from the Embedded View
    14val embeddedView = Plaid.createLinkEmbeddedView(
    15this /*Activity context*/,
    16linkTokenConfiguration,
    17linkAccountToPlaid) {
    18exit: LinkExit -> /* handle LinkExit (from Embedded View) */
    19 }
    20)
    21
    22// Add this embeddedView to a view in your layout
    23binding.embeddedViewContainer.addView(embeddedView)
    1<div id="plaid-embedded-link-container"></div>
    1// The container at `#plaid-embedded-link-container` will need to be sized in order to
    2// control the size of the embedded Plaid module
    3const embeddedLinkOpenTarget = document.querySelector('#plaid-embedded-link-container');
    4
    5Plaid.createEmbedded(
    6 {
    7 token: 'GENERATED_LINK_TOKEN',
    8 onSuccess: (public_token, metadata) => {},
    9 onLoad: () => {},
    10 onExit: (err, metadata) => {},
    11 onEvent: (eventName, metadata) => {},
    12 },
    13 embeddedLinkOpenTarget,
    14);
    1import React, { useCallback } from 'react';
    2import { PlaidEmbeddedLink } from 'react-plaid-link';
    3
    4const App = props => {
    5 const onSuccess = useCallback(
    6 (token, metadata) => console.log('onSuccess', token, metadata),
    7 []
    8 );
    9
    10 const onEvent = useCallback(
    11 (eventName, metadata) => console.log('onEvent', eventName, metadata),
    12 []
    13 );
    14
    15 const onExit = useCallback(
    16 (err, metadata) => console.log('onExit', err, metadata),
    17 []
    18 );
    19
    20 const config = {
    21 token: "plaid-token-123",
    22 onSuccess,
    23 onEvent,
    24 onExit,
    25 };
    26
    27 return (
    28 <PlaidEmbeddedLink
    29 {...config}
    30 style={{
    31 height: '350px',
    32 width: '350px',
    33 }}
    34 />
    35 );
    36};
    37
    38export default App;
    Update mode

    Embedded Institution Search cannot be used in update mode; to update a user's Item, launch a regular update mode session instead.

    Customization Options

    You can customize the Embedded Institution Search user experience to match your application's needs.

    Module responsiveness and tile count

    The embedded Link module will responsively scale to display between four and fifteen institutions, depending on the height and width of the module.

    WidthColumns
    > 572px5
    464-571px4
    356-463px3
    < 355px2
    HeightRows
    > 348px3
    282-347px2
    < 281px1

    On the web, the embedded Plaid module will attempt to use 100% of the height and width of its container. To modify the size of the Plaid module, or to render the Plaid module responsively, you should set the size of the container. We recommend using the largest container that will comfortably fit in your UI, with a minimum width of 240px. The larger the container, the more institution logos will be shown. A user seeing their institution's logo on the embedded Link screen has been shown to increase adoption of pay-by-bank.

    Success state

    You can optionally display a success state in the embedded Link module after the user has successfully connected their account. This success state will replace the Embedded Institution Search view with a visualization of the linked account. To enable this feature, talk to your Plaid account manager.

    Example Embedded Success State experience
    Example of viewing a successfully linked account in the Embedded Success State
    Customizing institutions displayed

    The institutions displayed in Link Embedded Search are based on your Institution Select settings, which you can optionally customize in the Dashboard. For most customers, it is recommended to use the default settings.

    Embedded Institution Search is compatible with the Institution Select Shortcut: If you already know which institution the user wants to connect to before initializing Link, you can pass routing_number into the institution_data request field in the /link/token/create endpoint. The matched institution will be listed first (top left position) in the embedded institution grid.

    Returning user experience

    The Embedded Institution Search experience can be further optimized for users who have already connected a financial account with Plaid.

    Example Embedded Institution Search returning user experience.
    Example of the returning user experience in Embedded Institution Search

    When a user's device is recognized or the phone number is provided via /link/token/create, Plaid will check to see if they are a returning user. If they are detected as a returning user, Plaid Link will run a security check on the session in the background. If this check passes, the user will be shown a list of previously connected accounts in the embedded module.

    The user can then verify the phone number using a one-time password and complete the account linking if the previously linked institutions do not require re-authentication. For more details on the returning user flow, see Returning user experience.

    Testing in Sandbox

    In order to test the returning user experience in Embedded Institution Search, use the phone numbers listed in Testing returning user experience in Sandbox.

    Event callbacks emitted by Embedded Institution Search

    User chooses an institution directly from embedded search
    • onEvent: OPEN – view_name: "CONSENT"
    • onEvent: SELECT_INSTITUTION
    • onEvent: TRANSITION_VIEW – view_name: "CONSENT"
    • onEvent: TRANSITION_VIEW – view_name: "CREDENTIAL" or "OAUTH" - user selects Continue on the ConsentPane

    UI Recommendations for Embedded Institution Search

    See Increasing pay-by-bank adoption for recommendations on displaying Embedded Institution Search within your app for pay-by-bank use cases.

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