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:
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 Item
s 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 theItem
was created using Instant Auth or Instant Match flows and no further action is required to complete authentication. - If
verification_status
ispending_automatic_verification
, then theItem
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
ispending_manual_verification
, then theItem
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>
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. The <client_name>
is defined by the "Company name" submitted during your Plaid Dashboard signup and it cannot be modified at this time — if you need it changed, please contact Plaid Support via this support case.