Flexible Auth

Flexible Auth lets end users choose upfront between instant account authentication and micro-deposits in the Plaid Link flow. By offering this choice, you can better convert users who can't or don't want to use credential-based Instant Auth. Integrations that use Flexible Auth can expect conversion improvements of up to 5-10 percentage points.

Flexible Auth provides an additional entry point into Same Day Micro-deposits.

To integrate with Flexible Auth, your application must be using Link tokens. If you are using a public key based integration instead, see the Link token migration guide.

Because Flexible Auth gives your users a choice between Same Day Micro-deposits and Instant Auth, you should only use Flexible Auth if your flow is compatible with the limitations of Same Day Micro-deposits: countries supported must be US only, you must not require the use of any Plaid products other than Auth, and your flow must support a delay of anywhere from several hours to 1-2 days between presenting Link and verifying the user's account.

The integration for Flexible Auth is identical to Same Day Micro-deposits, with the addition of the auth object to the request to /link/token/create to create a link_token. This is the only difference between the Same-Day Micro-deposits flow and the Flexible Auth flow.

• products array should include only auth as a product when using Same Day Micro-deposit verification. While in most cases additional products can be added to existing Plaid Items, Items created for same-day manual micro-deposit verification are an exception and cannot be used with any Plaid products other than Auth. To use another product with the same bank account, your user will need to re-link their account.
• country_codes set to ['US'] – Micro-deposit verification is currently only available in the United States.

1const request: LinkTokenCreateRequest = {
2  user: {
3    client_user_id: 'user-id',
4  },
5  client_name: 'Plaid Test App',
6  products: ['auth'],
7  country_codes: ['US'],
8  language: 'en',
9  webhook: 'https://sample-web-hook.com',
10  redirect_uri: 'https://domainname.com/oauth-page.html',
11  auth: {
12    flow_type: 'FLEXIBLE_AUTH',
13  },
14};
15try {
16  const response = await plaidClient.linkTokenCreate(request);
17  const linkToken = response.data.link_token;
18} catch (error) {
19  // handle error
20}

Once you’ve acquired the link_token, use it to initialize Link in order to exchange it for a public_token.

When the user successfully logs into their institution or inputs their account and routing numbers, the onSuccess() callback function will return a public_token.

1const linkHandler = Plaid.create({
2  // Fetch a link_token configured for 'auth' from your app server
3  token: (await $.post('/create_link_token')).link_token,
4  onSuccess: (public_token, metadata) => {
5    // Send the public_token and connected accounts to your app server
6    $.post('/get_access_token', {
7      publicToken: public_token,
8      accounts: metadata.accounts,
9    });
10
11    metadata = {
12      ...,
13      link_session_id: String,
14      institution: {
15        name: null,          // name is always null for same day micro-deposits
16        institution_id: null // institution_id is always null for same day micro-deposits
17      },
18      accounts: [{
19        id: 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D',
20        mask: '1234',
21        name: null,
22        type: 'depository',
23        subtype: 'checking' | 'savings',
24        verification_status: 'pending_manual_verification'
25      }]
26    }
27  },
28  // ...
29});
30
31// Open Link on user-action
32linkHandler.open();

Examine the value of metadata.accounts[0].verification_status returned by the onSuccess callback. If it is not returned or null, the user has chosen Instant Auth and you can proceed to call Auth endpoints. If it is pending_manual_verification, the user has chosen Same Day Micro-deposits. Proceed with the instructions for Same Day micro-deposits.