Hosted Link
Integrate with Link using a Plaid-hosted frontend
Overview
Hosted Link is the easiest and fastest way to integrate with Plaid. With Hosted Link, Plaid hosts the Link experience and opens it in a secure web context within a mobile app, eliminating the need for front-end implementation work. Hosted Link is especially recommended for any mobile integration that is not using the official Plaid SDK. If your Plaid integration uses webviews, we strongly recommend switching to Hosted Link. Hosted Link can also be used to complement in-person interactions; for example, you can send a Hosted Link session to customers who are in-person at a retail location.
Hosted Link is fully compatible with all Plaid products and Link flows, including update mode.
With Link Delivery (beta), Hosted Link can also deliver the URL for the Link session to your users via text or email.
Benefits of using Hosted Link
- Simplicity: Hosted Link is the easiest way to integrate with Plaid if you are unable to use Plaid's native mobile SDKs. You don't need to build or maintain a front-end component.
- Integration complexity: Since Hosted Link controls the redirections that are required to support OAuth, it removes one complex step to supporting embedded integrations.
- SDK size: Since the flow will be hosted by Plaid, there is no added SDK size to your application.
To request access to Hosted Link, contact your Account Manager.
Integration process
Creating a Link token
To start with Hosted Link, call /link/token/create
.
You can provide the following Hosted Link parameters to /link/token/create
:
- Specify a
webhook
endpoint where thepublic_token
will be delivered. Webhooks are strongly recommended when using Hosted Link, as the webhook is the primary means of delivering thepublic_token
, as well as of informing you when your user has completed the Link session. - To have Plaid deliver the link to your user with Link Delivery (beta), set
hosted_link.delivery_method
to eithersms
oremail
. Plaid will contact the user via the information you provide in theuser
object of the request. For example, if you selectedemail
, theuser
object in the request must contain anemail_address
. - To customize the duration of the Hosted Link token lifetime, set
hosted_link.url_lifetime_seconds
. If you don't set this field, the default lifetime for Hosted Links sent by Plaid via SMS is 24 hours, and for links sent via email, it is 7 days. If Plaid isn't delivering the url, the default lifetime is 30 minutes. - To have Plaid redirect the user after they complete the Link flow, set
hosted_link.completion_redirect_uri
to the destination URI. - To indicate that the user will be opening the link in a mobile app in an out-of-process webview (i.e., an
AsWebAuthenticationSession
/SFSafariViewController
or Chrome Custom Tab), sethosted_link.is_mobile_app
totrue
.
Once you’ve been enabled for Hosted Link, every successful response from /link/token/create
will include a hosted_link_url
field. You can send a user to this URL to start the Hosted Link session. Alternatively, if your integration uses both Hosted Link and non-Hosted Link sessions, you can start a non-Hosted Link session using the link_token
instead.
1curl -X POST https://production.plaid.com/link/token/create \2-H 'Content-Type: application/json' \3-d '{4 "client_id": "${PLAID_CLIENT_ID}",5 "secret": "${PLAID_SECRET}",6 "client_name": "Wonderwallet",7 "country_codes": ["US"],8 "redirect_uri": "{{UNIVERSAL_OR_APP_LINK}}",9 "webhook": "https://wonderwallet.com/webhook_receiver",10 "language": "en",11 "user": {12 "client_user_id": "a57d3304",13 "phone_number": "+19162255887"14 },15 "products": ["auth"],16 "hosted_link": {17 "delivery_method": "sms",18 "completion_redirect_uri": "https://wonderwallet.com/redirect",19 "is_mobile_app": false,20 "url_lifetime_seconds": 90021 }22}
1{2 "expiration": "2023-08-18T02:08:03Z",3 "hosted_link_url": "https://secure.plaid.com/link/lp9o97618r1r6p93oon62nr025950ro4s3",4 "link_token": "link-production-4b42163e-6e1c-48bb-a17a-e570405eb9f8",5 "request_id": "kNbPMmLxzBObzpt"6}
Obtaining a public token
In most other Plaid integration methods, upon completion of the Link flow, your frontend code would receive either an onSuccess
or onExit
callback. In Hosted Link, there is no frontend integration required (or possible). You will instead receive information about the Link flow (including the public_token
) via the SESSION_FINISHED
webhook and the /link/token/get
endpoint.
Each time a user completes a Link flow, Plaid will fire a SESSION_FINISHED
webhook that contains information about what caused the session to end, as well as the public token if the session completed successfully. In flows where Link is re-initialized after an OAuth redirect, this webhook will fire exactly once, after the user completes the entire Link flow.
You can also call /link/token/get
with the relevant Link token to receive more detailed metadata on sessions started using this Link token. Each Link session includes the time it was started, and (if applicable) the time it finished. Each completed Link session also includes the metadata that would normally be passed to the onSuccess
or onExit
callbacks, including the public_token
for successful sessions.
Session data will be available from /link/token/get
for six hours after the session has completed. If you need to access Plaid products immediately after the user has completed the flow, you should listen for the webhook. For use cases that are not time sensitive, you can instead periodically poll the /link/token/get
endpoint.
1{2 "created_at": "2023-12-02T21:14:54Z",3 "expiration": "2023-12-03T01:14:54Z",4 "link_token": "link-sandbox-33792986-2b9c-4b80-b1f2-518caaac6183",5 "link_sessions": [6 {7 "events": [8 {9 "event_id": "8dda07e8-e2fb-4126-89e3-1024883a7043",10 "event_metadata": {11 "institution_id": "ins_127989",12 "institution_name": "Bank of America",13 "request_id": "QKtjaX8Z6xFcVGD"14 },15 "event_name": "HANDOFF",16 "timestamp": "2023-08-15T12:36:06Z"17 },18 {19 "event_id": "cf5f60f9-269b-40fe-bc01-1cfdc0a650a5",20 "event_metadata": {21 "institution_id": "ins_127989",22 "institution_name": "Bank of America",23 "request_id": "cPKgvrh4bfGGtp5"24 },25 "event_name": "TRANSITION_VIEW",26 "timestamp": "2023-08-15T12:36:05Z"27 },28 {29 "event_id": "231b88e8-53cf-4e80-b63e-55780798691f",30 "event_metadata": {31 "institution_id": "ins_127989",32 "institution_name": "Bank of America",33 "request_id": "b9rJOtqg2deGLiz"34 },35 "event_name": "SUBMIT_CREDENTIALS",36 "timestamp": "2023-08-15T12:36:00Z"37 },38 {39 "event_id": "e9a91a48-cfe3-4a0f-bc9b-1e3810ac71ee",40 "event_metadata": {41 "institution_id": "ins_127989",42 "institution_name": "Bank of America",43 "institution_search_query": "bofa",44 "request_id": "sjGooTOF4f3KJ5T"45 },46 "event_name": "SELECT_INSTITUTION",47 "timestamp": "2023-08-15T12:35:53Z"48 },49 {50 "event_id": "7499c0ed-2d38-4db1-9763-aeeab34a1255",51 "event_metadata": {52 "request_id": "sjGooTOF4f3KJ5T"53 },54 "event_name": "OPEN",55 "timestamp": "2023-08-15T12:35:48Z"56 }57 ],58 "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171",59 "started_at": "2023-08-15T12:34:56Z",60 "finished_at": "2023-08-15T12:36:54Z",61 "on_success": {62 "public_token": "public-sandbox-5c224a01-8314-4491-a06f-39e193d5cddc",63 "metadata": {64 "institution": {65 "name": "Bank of America",66 "institution_id": "ins_127989"67 },68 "accounts": {69 "account_id": "5Bvpj4QknlhVWk7GygpwfVKdd133GoCxB814g",70 "mask": "4444",71 "name": "Plaid Money Market",72 "subtype": "money market",73 "type": "depository"74 },75 "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171"76 }77 }78 },79 {80 "events": [81 {82 "event_id": "50f6e470-5622-4b6d-9cd0-37803c132860",83 "event_metadata": {84 "exit_status": "requires_recaptcha",85 "institution_id": "ins_127989",86 "institution_name": "Bank of America",87 "request_id": "URnaQNVCCRsYsAK"88 },89 "event_name": "EXIT",90 "timestamp": "2023-08-15T12:38:17Z"91 },92 {93 "event_id": "bf7a91dc-b502-4349-a2ec-c1ea6f898be0",94 "event_metadata": {95 "institution_id": "ins_127989",96 "institution_name": "Bank of America",97 "request_id": "ElGmk4ZPc90nobq"98 },99 "event_name": "TRANSITION_VIEW",100 "timestamp": "2023-08-15T12:38:11Z"101 },102 {103 "event_id": "f10b364a-e8b9-4096-ad8e-52b4fe107d74",104 "event_metadata": {105 "institution_id": "ins_127989",106 "institution_name": "Bank of America",107 "request_id": "0ObbDJVDlqzi6NQ"108 },109 "event_name": "SUBMIT_CREDENTIALS",110 "timestamp": "2023-08-15T12:38:11Z"111 },112 {113 "event_id": "93067419-4b03-446a-bf2d-b13450985b7f",114 "event_metadata": {115 "institution_id": "ins_127989",116 "institution_name": "Bank of America",117 "institution_search_query": "bank of america",118 "request_id": "yI0BAsJe5TIAkHY"119 },120 "event_name": "SELECT_INSTITUTION",121 "timestamp": "2023-08-15T12:38:05Z"122 },123 {124 "event_id": "a96f36b8-f080-4dda-ba51-26848a52d0d3",125 "event_metadata": {126 "institution_search_query": "bank of america",127 "request_id": "yI0BAsJe5TIAkHY"128 },129 "event_name": "SEARCH_INSTITUTION",130 "timestamp": "2023-08-15T12:37:54Z"131 },132 {133 "event_id": "e0c9a9d8-1d46-4e37-8efa-8032ced40467",134 "event_metadata": {135 "request_id": "yI0BAsJe5TIAkHY"136 },137 "event_name": "OPEN",138 "timestamp": "2023-08-15T12:37:47Z"139 }140 ],141 "link_session_id": "f742cae8-31e4-49cc-a621-6cafbdb26fb9",142 "started_at": "2023-08-15T12:37:01Z",143 "finished_at": "2023-08-15T12:40:35Z",144 "on_exit": {145 "error": {146 "error_type": "RECAPTCHA_ERROR",147 "error_code": "RECAPTCHA_REQUIRED",148 "error_message": "This request requires additional verification. Please resubmit the request after completing the challenge",149 "display_message": null,150 "status": 400151 },152 "metadata": {153 "institution": {154 "name": "Bank of America",155 "institution_id": "ins_127989",156 "status": "requires_questions"157 }158 }159 }160 }161 ],162 "request_id": "HNTDNrA8F1shFEW"163}
Migrating to Hosted Link from other integrations
First, review the Integration process to understand how to launch the Hosted Link flow and the configuration options available.
If you're currently capturing Link session events, migrate to using /link/token/get
to receive Link session events.
If your users will be opening Link sessions inside a native mobile application, launch Hosted Link in an out-of-process webview (i.e., an AsWebAuthenticationSession
/ SFSafariViewController
or Chrome Custom Tab) or an external browser instead of an in-process webview. The host app should manage opening the Hosted Link URL in this out-of-process webview and handle its closure. Without a provided callback, Plaid will show a page after a session ends, instructing users to return to the host app.
The hosted_link.completion_redirect_uri
parameter should be a URL that handles the redirect back to the host app. For example, on iOS using AsWebAuthenticationSession
(on Android you may be using Custom Tabs), the page that loads at the completion_redirect_uri
should redirect to a URL scheme you have pre-configured to close the the AsWebAuthenticationSession
. See the Apple Developer Documentation or Chrome Developer Documentation for more details.
(Optional) Make sure the provided redirect_uri
is a universal link that redirects users back to your app to enable Chase App-to-App authentication. As long as the link opens your application, you don't need to do any additional work to handle it.
iFrame based nested integrations
For nested integrations like iFrames in a customer web page within a merchant webview, shift from capturing events through redirects to using backend events via /link/token/get
. Your merchants should launch Hosted Link in an out-of-process webview or external browser.
Either you or the merchant must add an extra callback parameter to /link/token/create
, allowing Plaid to close the out-of-process webview as needed. You will likely make the /link/token/create
call. Merchants must either obtain a callback from the customer or ensure handling of a specified callback in their code.
Next steps
Once you have obtained a public token, you can integrate via the same process as non-Hosted Link integrations, including calling /item/public_token/exchange
to exchange the public token for an access token.
Testing Hosted Link
You can test Hosted Link in Production, Development, or Sandbox. In the Sandbox environment, Plaid will not provide email or SMS Hosted Link delivery.