Account Select v2 migration guide

Plaid has introduced an updated Account Select pane (Account Select v2). This improved experience gives users even more control over and transparency into the accounts they share with you and Plaid. When using Account Select v2, if a user links an Item at an institution where they hold more than one financial account, you will only receive data from the specific accounts the user has selected to share with you. When a user doesn't select a certain account on this pane, data associated with that account is not shared with you.

This guide covers the client and server-side changes required to implement the updated Account Select pane.

1. The API will only return data for the accounts the user has selected for Items created with Account Select v2 enabled (existing Items will not be affected). The Account Select pane can be configured to the "Enabled for one account", "Enabled for multiple accounts", or "Enabled for all accounts" behavior.
2. A new NEW_ACCOUNTS_AVAILABLE webhook is available to notify you when a user may have a new account available to connect. To request a new account from a user, you can use Link in update mode.

1. Review the implementation considerations.
2. Update each of your Link customizations to Account Select v2
3. (Optional) Listen for the new NEW_ACCOUNTS_AVAILABLE webhook and integrate update mode with Account Select enabled.
4. Disable Account Select v1

Account Select v2 only returns data for accounts the user has selected. If your app currently depends on having access to all accounts associated with an Item as well as all future new accounts going forward (e.g. some personal financial management apps), we recommend making the following implementation changes:

1. Configure Account Selection V2 with the "Enabled for all accounts" behavior, so that the pane automatically requires access to all accounts.
2. If you’re using the NEW_ACCOUNTS_AVAILABLE webhook to prompt users to link additional accounts, you might want to provide context explaining why the user is being prompted to proceed through update mode.
3. If you have built your own account management feature where users can link additional accounts directly from your app without having to go through update mode, you might want to update the in-app copy to clarify that the user will need to proceed through Link in order to add new accounts. You will also need to configure this feature to initiate update mode with Account Select enabled.

To opt into Account Select v2, go to your Link customization or create a new one (you may duplicate an existing customization by using the duplicate feature), click on the Version 2.0 tab, and select one of the new view behaviors:

• Enabled for one account
• Enabled for multiple accounts
• Enabled for all accounts

Once you’ve selected a Version 2.0 View Behavior, click Publish. Your changes will go into effect the next time you initialize Link with this customization. Only newly created Items created with the updated customization will have the new API behavior; existing Items will not be affected.

If you want to downgrade to the previous experience, you can do so until March 2022 by clicking the Version 1.0 tab and clicking Publish. After March 2022 Account Select v1 will automatically be updated to Account Select v2. See automatic migration for more details.

We recommend that if you’re currently using the Account Select pane, you maintain the existing view behavior when you migrate to Account Select v2. If you haven’t used the Account Select pane before, you may want to consider the following:

• If your Plaid use case is banking, consumer payments, or wealth, we recommend that you use the "Enabled for one account" or the "Enabled for multiple accounts" view behavior.
• If your Plaid use case is personal financial management or lending, you may prefer to use the "enabled for all accounts" view behavior.

Plaid will issue webhooks to you whenever we discover new accounts for your user. You can find out about these new accounts by listening for the NEW_ACCOUNTS_AVAILABLE webhook.

To add these new accounts, initialize Link for update mode. Your call to /link/token/create must include the following:

1. The update.account_selection_enabled flag set to true. To ensure you are able to use this flag, check that your Plaid library meets the minimum version required.
2. A link_customization_name for a customization that enables Account Select v2. The settings on this customization will determine which View Behavior for the Account Select pane is shown in update flow. You may omit this parameter if your default customization has Account Select v2 enabled.
3. (Optional) Any account_filters to specify account filtering. Note that this field cannot be set for update mode if account selection is not enabled.

1curl -X POST https://sandbox.plaid.com/link/token/create \
2-H 'Content-Type: application/json' \
3-d '{
4  "client_id": "CLIENT_ID",
5  "secret": "SECRET",
6  "client_name": "My App",
7  "user": { "client_user_id": "UNIQUE_USER_ID" },
8  "country_codes": ["US"],
9  "language": "en",
10  "webhook": "https://webhook.sample.com",
11  "access_token": "ENTER_YOUR_ACCESS_TOKEN",
12  "link_customization_name": "account_selection_v2_customization",
13  "update": { "account_selection_enabled": true }
14}'

Once your user has updated their account selection, all selected accounts will be shared in the accounts field in the onSuccess() callback from Link.

1const onSuccess = useCallback<PlaidLinkOnSuccess>(
2 (public_token: string, metadata: PlaidLinkOnSuccessMetadata) => {
3   // updated selected account ids
4   const account_ids = metadata.accounts.map(account => account.id);
5   // ...
6 },
7 [],
8);

Any de-selected accounts will no longer be shared with you. You will only receive data for accounts the user selects in update mode going forward.

We recommend that you remove any data associated with accounts your user has de-selected.

If the consumer shares new accounts for an Item initialized with the Transactions product, Plaid will send a TRANSACTIONS: INITIAL_UPDATE webhook and a TRANSACTIONS: HISTORICAL_UPDATE webhook when the initial and historical transaction updates complete for the new account selections.

You can test Account Select v2 in Sandbox by creating a Link customization with Account Select v2 enabled specifically for testing and initializing Link with that customization in the Sandbox environment. This will not impact production traffic.

To verify that you’re correctly handling the NEW_ACCOUNTS_AVAILABLE webhook, you can use the /sandbox/item/fire_webhook endpoint or you can use custom Sandbox data to trigger a change in accounts that will cause the webhook to fire:

1. Create an Item in Link with Account Select v2 with the following configuration object:

   Configuration to create item

   Copy

   1{
   2  "override_accounts": [
   3    {
   4      "type": "depository",
   5      "subtype": "checking"
   6    }
   7  ]
   8}

Make sure that you have obtained an access_token corresponding to the configuration object before proceeding to the next step.

1. Update the Item by changing the configuration object to add another account:

   Configuration to add an account

   Copy

   1{
   2  "override_accounts": [
   3    {
   4      "type": "depository",
   5      "subtype": "checking"
   6    },
   7    {
   8      "type": "depository",
   9      "subtype": "savings"
   10    },
   11  ]
   12}

2. The NEW_ACCOUNTS_AVAILABLE webhook should fire when Plaid runs its next periodic check for account updates, typically within 6 to 24 hours. Or, to force the check to occur immediately, you can go through the update mode flow for the Item.

Once you have migrated each of your customizations to Account Select v2, go to the Migrations page in Team Settings and click Migrate.

This will remove the Version 1.0 tab from the Account Select customization options. Going forward, all new customizations will be created with the Account Select pane’s behavior set to "Enabled for multiple accounts" by default.

If you did not migrate to Account Select v2 by March 2022, Plaid automatically migrated all of your customizations to Account Select v2, using the following rules:

• If your customization has disabled Account Select v1, we defaulted you to the "Enabled for all accounts" Account Select v2 view behavior.
• If your customization has enabled single select Account Select v1, we defaulted you to the "Enabled for one account select" Account Select v2 view behavior.
• If your customization has enabled multi select Account Select v1, we defaulted you to the "Enabled for multiple accounts" Account Select v2 view behavior.

• Python - 8.3.0
• Node - 9.3.0
• Ruby - 14.3.0
• Java - 9.3.0
• Go - 1.3.0