Overview

This article outlines the various user authentication methods into their financial institution that Plaid supports. It’s meant to be a primer and not a replacement for Plaid's Developer Documentation, which goes into full detail. Each section is broken down into steps, supporting code samples, and references to specific sections in Plaid’s Developer Documentation when available.

There are four Auth flows to build for:

Instant Auth: User enters their credentials and are authenticated immediately.
Instant Match: User enters their credentials, account number, and routing number. Plaid matches user input and authenticates immediately.
Automated Microdeposits: User enters their credentials, account number, and routing number. Plaid makes 1 microdeposit and automatically verifies the deposit within 1-2 business days.
Same Day Microdeposits: User enters account and routing numbers. Plaid makes 2 Same Day ACH microdeposits and the user manually verifies the deposits within 1 business day.

Each Auth flow will require specific user flows, token management, and API requests to complete the integration.

Jump to:

Instant Auth

Instant Match

Automated Microdeposits

Same Day Microdeposits

Handling onSuccess() callback

Microdeposit transaction description

Plaid Link

Each authentication path detailed in this document requires Plaid Link, Plaid’s front-end module that handles user authentication to financial institutions. It is available on:

Web (Javascript, React, and more)
iOS (native SDK or WebView)
Android (native SDK or WebView)
React Native

Upon successful user login, the onSuccess() callback function will return a public_token. This public_token must be exchanged for an access_token, and the access_token should be persisted in relation to a user because the access_token is required to make subsequent requests to any of Plaid's other API endpoints.

See our Developer Documentation for full instructions on how to integrate Plaid Link, and check out our Quickstart and example applications to begin building your Plaid integration fast and with ease.

Auth Flows

Read our Developer Documentation for full instructions on integrating our Auth Flows and using our client libraries for making API requests to Plaid.

Instant Auth

1. Initialize Plaid Link with a product array and webhook URL

Plaid.create({
  //...
  product: ['auth'],
  webhook: 'https://your_app_url.com/webhook'
  //...
});

2. User inputs username & password for their financial institution

3. onSuccess() callback function will return a public_token and send to backend

Plaid.create({
  //...
  onSuccess: function(public_token, metadata) {
    // Send the public_token to your app server.
    // The metadata object contains info about the institution the
    // user selected and the account ID or IDs, if the
    // Select Account view is enabled.
    $.post('/get_access_token', {
      public_token: public_token,
    });
  },
  //...
});

4. Call the /item/public_token/exchange endpoint with a public_token to obtain an access_token

Request

curl -X POST https://sandbox.plaid.com/item/public_token/exchange \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": String,
    "secret": String,
    "public_token": "public-sandbox-5c224a01-8314-4491-a06f-39e193d5cddc"
  }'

Response

{
  "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
  "request_id": "Aim3b"
}

5. Persist access_token & item_id in your database in relation to the user

6. You can now use the access_token to issue requests to the Plaid API

Instant Match

1. Initialize Plaid Link with a product array and webhook URL. The countryCodes parameter must be set to US.

Plaid.create({
  //...
  product: ['auth'],
  countryCodes: ['US'],
  webhook: 'https://your_app_url.com/webhook',
  //...
});

2. User inputs username & password and account & routing number for their financial institution

3. onSuccess() callback function will return a public_token and send to backend

Plaid.create({
  //...
  onSuccess: function(public_token, metadata) {
    // Send the public_token to your app server.
    // The metadata object contains info about the institution the
    // user selected and the account ID or IDs, if the
    // Select Account view is enabled.
    $.post('/get_access_token', {
      public_token: public_token,
    });
  },
  //...
});

4. Call the /item/public_token/exchange endpoint with a public_token to obtain an access_token

Request

curl -X POST https://sandbox.plaid.com/item/public_token/exchange \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": String,
    "secret": String,
    "public_token": "public-sandbox-5c224a01-8314-4491-a06f-39e193d5cddc"
  }'

Response

{
  "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
  "request_id": "Aim3b"
}

5. Persist access_token & item_id in your database in relation to the user

6.You can now use the access_token to issue requests to the Plaid API

Automated Microdeposits

1. Initialize Plaid Link with a product array and webhook URL. The countryCodes parameter must be set to US. A webhook URL is required for Automated Microdeposits.

Plaid.create({
  //...
  product: ['auth'],
  countryCodes: ['US'],
  // we require a webhook for automated microdeposits,
  // for successful or unsuccessful verification
  webhook: 'https://your_app_url.com/webhook'
  //...
});

2. User inputs username & password and account & routing number for their financial institution

3. onSuccess() callback function will return a public_token and send to backend

Plaid.create({
  //...
    onSuccess: function(public_token, metadata) {
      // Send the public_token to your app server.
      // The metadata object contains info about the institution the
      // user selected and the account ID or IDs, if the
      // Select Account view is enabled.
      $.post('/get_access_token', {
        public_token: public_token,
      });
    },
  //...
});

4. Call the /item/public_token/exchange endpoint with a public_token to obtain an access_token

Request

curl -X POST https://sandbox.plaid.com/item/public_token/exchange \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": String,
    "secret": String,
    "public_token": "public-sandbox-5c224a01-8314-4491-a06f-39e193d5cddc"
  }'

Response

{
  "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
  "request_id": "Aim3b"
}

5. Persist access_token & item_id in your database in relation to the user

6. You will receive a AUTOMATICALLY_VERIFIED webhook when the user's account has been automatically verified by Plaid. Note: if you try to issue an API request before the account has been verified, you will receive a PRODUCT_NOT_READY error. If you are using the Sandbox environment, you can use the /sandbox/item/set_verification_status endpoint to test your integration. Please refer to our Auth webhooks documentation for more information.

{
  "webhook_type": "AUTH",
  "webhook_code": "AUTOMATICALLY_VERIFIED",
  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
  "account_id": "xxxxxx"
}

7. You can now use the access_token to issue requests to the Plaid API

Same Day Microdeposits

1. Initialize Plaid Link with a product array and webhook URL. The countryCodes parameter must be set to US. For Same Day Microdeposits, auth must be the the only product.

Plaid.create({
  //...
  product: ['auth'], // auth must be the only product
  countryCodes: ['US'],
  webhook: 'https://your_app_url.com/webhook'
  //...
});

2. User inputs their name, account & routing number for their financial institution

3. onSuccess() callback function will return a public_token and send to backend

Plaid.create({
  //...
    onSuccess: function(public_token, metadata) {
      // Send the public_token to your app server.
      // The metadata object contains info about the institution the
      // user selected and the account ID or IDs, if the
      // Select Account view is enabled.
      $.post('/get_access_token', {
        public_token: public_token,
      });
    },
  //...
});

4. Call the /item/public_token/exchange endpoint with a public_token to obtain an access_token

Request

curl -X POST https://sandbox.plaid.com/item/public_token/exchange \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": String,
    "secret": String,
    "public_token": "public-sandbox-5c224a01-8314-4491-a06f-39e193d5cddc"
  }'

Response

{
  "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
  "request_id": "Aim3b"
}

5. Plaid will automatically send 2 microdeposits to the user’s account once the token exchange has occurred

6. Persist access_token & item_id in your database in relation to the user

7. After 2-3 business days, you should send the user a notification (e.g. email, SMS, push) informing them to verify in your app the 2 posted microdeposits Plaid automatically posted to their account

8. Generate a new public_token by passing access_token to the /item/public_token/create endpoint

Request

curl -X POST https://sandbox.plaid.com/item/public_token/create \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": String,
    "secret": String,
    "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6"
  }'

Response

{
  "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
  "request_id": "Aim3b"
}

9. Initialize Plaid Link with a product array, webhook URL, and public_token

Plaid.create({
  //...
  product: ['auth'],
  webhook: 'https://your_app_url.com/webhook',
  token: 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d'
  //...
});

10. Plaid Link opens directly to the authentication step for that institution for users to verify their account by inputting the 2 posted microdeposits Plaid automatically posted to their account

11. You can now use the access_token to issue requests to the Plaid API. Note: when issuing /item/get requests, the institution_id value will be null for Items created via Same Day Microdeposits, per the Item Schema.

Handling `onSuccess()` callback

In the onSuccess() Link callback, the field accounts.verification_status field will indicate the flow through which theItem was created:

If verification_status is null, then the Item was created using Instant Auth or Instant Match flows and no further action is required to complete authentication.
If verification_status is pending_automatic_verification, then the Item was created through the Automated Microdeposits flow and your application will receive an Auth webhook when the verification completes (AUTOMATICALLY_VERIFIED) or expires (VERIFICATION_EXPIRED).
If verification_status is pending_manual_verification, then the Item was created through the Same Day Microdeposits flow and the user must come back in 1-2 days to verify the amounts posted to their account.

See onSuccess() callback for complete documentation.

Microdeposit transaction description

When the microdeposits post to your end-user's bank account, the transaction description will be written with the format:

<client_name> deposit {1,2}

Plaid will reverse the microdeposits at the same time they are sent — the transaction description will be written with the format:

<client_name> reverse {1, 2}

The <client_name> is defined by the "Company name" submitted during your Plaid Dashboard signup and it cannot be modified at this time. The <client_name> will be formatted in snake_case, and the maximum <client_name> shown in the transaction description is 16 characters in length — any additional characters will be truncated.

Jump back to top.

Articles in this section

Overview

Plaid Link

Auth Flows

Instant Auth

Instant Match

Automated Microdeposits

Same Day Microdeposits

Handling onSuccess() callback

Microdeposit transaction description

Handling `onSuccess()` callback