Auth (2024)

The Automated Micro-deposits authentication flow is supported for over 1,000 financial institutions in the US only, accounting for approximately <1% of depository accounts.Plaid will make a single micro-deposit and then automatically verify it within one to two business days.

You can try out the Automated Micro-deposits flow in Link Demo. See more details in our testing guide.

A user connects their financial institution using the following connection flow:

1. Starting on a page in your app, the user clicks an action that opens Plaid Link, with the correctAuth configuration.
2. Inside of Plaid Link, the user selects their institution, authenticates with their credentials,provides their account and routing number, and enters in their legal name.
3. Upon successful authentication, Link closes with apublic_token and a metadata account status of pending_automatic_verification.
4. Behind the scenes, Plaid sends a single micro-deposit to the user's account and will automaticallyverify the deposited amounts within one to two business days.
5. When verification succeeds or fails, Plaid sends an Auth webhook,which you can use to notify the user that their account is ready to move money. Once this step is done, your user's Auth data is verified and ready to fetch.

Create a link_token with the following parameters:

• products array containing auth or transfer -- unlike with Same-Day Micro-deposits, you can also include other products besides auth or transfer when creating a Link token for use with Automated Micro-deposits, but auth or transfer must be present.
• country_codes set to ['US'] – Micro-deposit verification is currently only available in the United States.
• A webhook URL to receive a POST HTTPS request sent from Plaid's servers to your applicationserver, after Automated Micro-deposits succeeds or fails verification of a user's micro-deposits.
• auth object should specify "automated_microdeposits_enabled": true

1const request: LinkTokenCreateRequest = {
2 user: { client_user_id: new Date().getTime().toString() },
3 client_name: 'Plaid App',
4 products: [Products.Auth],
5 country_codes: [CountryCode.Us],
6 language: 'en',
7 auth: {
8 automated_microdeposits_enabled: true,
9 },
10};
11try {
12 const response = await plaidClient.linkTokenCreate(request);
13 const linkToken = response.data.link_token;
14} catch (error) {
15 // handle error
16}

After creating a link_token for the auth product, use it to initialize Plaid Link.

When the user inputs their username and password, and account and routing numbers for the financial institution,the onSuccess() callback function will return a public_token, with verification_status equal to 'pending_automatic_verification'.

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 accounts to your app server
6 $.post('/exchange_public_token', {
7 publicToken: public_token,
8 accounts: metadata.accounts,
9 });
10
11 metadata = {
12 ...,
13 link_session_id: String,
14 institution: { name: 'Bank of the West', institution_id: 'ins_100017' },
15 accounts: [{
16 id: 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D',
17 mask: '1234',
18 name: null,
19 type: 'depository',
20 subtype: 'checking' | 'savings',
21 verification_status: 'pending_automatic_verification'
22 }]
23 }
24 },
25 // ...
26});
27
28// Open Link on user-action
29linkHandler.open();

Because Automated verification usually takes between one to two days to complete, we recommend displaying a UIin your app that communicates to a user that verification will occur automatically and is currently pending.

You can use the verification_status key returned in the onSuccess metadata.accounts object oncePlaid Link closes successfully.

1verification_status: 'pending_automatic_verification';

You can also fetch the verification_status for anItem's account via the Plaid API to obtain the latest account status.

In your own backend server, call the /item/public_token/exchangeendpoint with the Link public_token received in the onSuccess callback to obtain an access_token.Persist the returned access_token and item_id in your database in relation to the user.

Note that micro-deposits will only be delivered to the ACH network in the Production environment. To test your integration outside of Production, see Testing automated micro-deposits in Sandbox.

Select group for content switcher

1// publicToken and accountID are sent from your app to your backend-server
2const accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D';
3const publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d';
4
5// Obtain an access_token from the Link public_token
6const response = await client
7 .itemPublicTokenExchange({
8 public_token: publicToken,
9 })
10 .catch((err) => {
11 // handle error
12 });
13const accessToken = response.access_token;

1{
2 "access_token": "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755",
3 "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
4 "request_id": "m8MDnv9okwxFNBV"
5}

Before you can call /auth/get to fetch Auth data for a user's access_token, a micro-deposit firstneed to post successfully to the user's bank account. Because Plaid uses Same Day ACH to send asingle micro-deposit amount, this process usually takes between one to two days.

Once the deposit has arrived in the user's account, Plaid will automatically verify the deposittransaction and send an AUTOMATICALLY_VERIFIEDwebhook to confirm the account and routing numbers have been successfully verified.

1> POST https://your_app_url.com/webhook
2
3{
4 "webhook_type": "AUTH",
5 "webhook_code": "AUTOMATICALLY_VERIFIED",
6 "item_id": "zeWoWyv84xfkGg1w4ox5iQy5k6j75xu8QXMEm",
7 "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D"
8}

Occasionally automatic verification may fail, likely due to erroneous user input, such as an incorrectaccount and routing number pair. If the Item is unable to be verified within seven days, Plaid will senda VERIFICATION_EXPIREDwebhook. When verification fails, the Item is permanently locked; we recommend prompting your user toretry connecting their institution via Link.

1> POST https://your_app_url.com/webhook
2
3{
4 "webhook_type": "AUTH",
5 "webhook_code": "VERIFICATION_EXPIRED",
6 "item_id": "zeWoWyv84xfkGg1w4ox5iQy5k6j75xu8QXMEm",
7 "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D"
8}

The example code below shows how to handle AUTOMATICALLY_VERIFIED and VERIFICATION_EXPIRED webhooksand call /auth/get to retrieve account and routing data.

Select group for content switcher

1// This example uses Express to receive webhooks
2const app = require('express')();
3const bodyParser = require('body-parser');
4app.use(bodyParser);
5
6app.post('/webhook', async (request, response) => {
7 const event = request.body;
8
9 // Handle the event
10 switch (event.webhook_code) {
11 case 'AUTOMATICALLY_VERIFIED':
12 const accessToken = lookupAccessToken(event.item_id);
13 const request: AuthGetRequest = { access_token: accessToken };
14 const authResponse = await client.authGet(request);
15 const numbers = authResponse.numbers;
16 break;
17 case 'VERIFICATION_EXPIRED':
18 // handle verification failure; prompt user to re-authenticate
19 console.error('Verification failed for', event.item_id);
20 break;
21 default:
22 // Unexpected event type
23 return response.status(400).end();
24 }
25
26 // Return a response to acknowledge receipt of the event
27 response.json({ received: true });
28});
29
30app.listen(8000, () => console.log('Running on port 8000'));

In some cases you may want to implement logic to display the verification_status of an Itemthat is pending automated verification in your app. The /accounts/getAPI endpoint allows you to query this information.

Select group for content switcher

1// Fetch the accountID and accessToken from your database
2const accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D';
3const accessToken = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755';
4const request: AccountsGetRequest = {
5 access_token: accessToken,
6};
7const response = await client.accountsGet(request).catch((err) => {
8 // handle error
9});
10const account = response.accounts.find((a) => a.account_id === accountID);
11const verificationStatus = account.verification_status;

1{
2 "accounts": [
3 {
4 "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
5 "balances": { Object },
6 "mask": "0000",
7 "name": "Plaid Checking",
8 "official_name": "Plaid Gold Checking",
9 "type": "depository"
10 "subtype": "checking" | "savings",
11 "verification_status":
12 "pending_automatic_verification" |
13 "automatically_verified" |
14 "verification_expired",
15 },
16 ...
17 ],
18 "item": { Object },
19 "request_id": String
20}

Finally, we can retrieve Auth data once automated verification has succeeded:

Select group for content switcher

1const accessToken = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755';
2
3// Instantly fetch Auth numbers
4const request: AuthGetRequest = {
5 access_token: accessToken,
6};
7const response = await client.authGet(request).catch((err) => {
8 // handle error
9});
10const numbers = response.numbers;

1{
2 "numbers": {
3 "ach": [
4 {
5 "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
6 "account": "9900009606",
7 "routing": "011401533",
8 "wire_routing": "021000021"
9 }
10 ],
11 "eft": [],
12 "international": [],
13 "bacs": []
14 },
15 "accounts": [
16 {
17 "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
18 "balances": { Object },
19 "mask": "0000",
20 "name": null,
21 "official_name": null,
22 "verification_status": "automatically_verified",
23 "subtype": "checking" | "savings",
24 "type": "depository"
25 }
26 ],
27 "item": { Object },
28 "request_id": "m8MDnv9okwxFNBV"
29}

Check out the /auth/get API reference documentation to see the fullAuth request and response schema.

For a user who goes through the Automated Micro-deposit flow, the TRANSITION_VIEW (view_name = NUMBERS)event will occur after SUBMIT_CREDENTIALS, and in the onSuccess callback theverification_status will be pending_automatic_verification.

1OPEN (view_name = CONSENT)
2TRANSITION_VIEW view_name = SELECT_INSTITUTION)
3SEARCH_INSTITUTION
4SELECT_INSTITUTION
5TRANSITION_VIEW (view_name = CREDENTIAL)
6SUBMIT_CREDENTIALS
7TRANSITION_VIEW (view_name = LOADING)
8TRANSITION_VIEW (view_name = MFA, mfa_type = code)
9SUBMIT_MFA (mfa_type = code)
10TRANSITION_VIEW (view_name = LOADING)
11TRANSITION_VIEW (view_name = SELECT_ACCOUNT)
12TRANSITION_VIEW (view_name = NUMBERS)
13TRANSITION_VIEW (view_name = LOADING)
14TRANSITION_VIEW (view_name = CONNECTED)
15HANDOFF
16onSuccess (verification_status: pending_automatic_verification)