Plaid FAQs

Occasionally, an Item will need to have authentication information updated. When this happens, the Item will go into an error state. A common cause for this is if your user updates their credentials with their institution.

You will be notified when an Item goes into error state via a webhook (recommended) or an error response to an API request. When this happens, we recommend you notify your user via an email or push notification and request that they enter your application to update their authentication details. Within your application, launching Plaid Link in update mode will allow your user to re-authenticate with Plaid.

here

Item error webhook sent to your application

The recommended way to getting notified of an Item going into an error state is via webhooks. We will notify you that anItem's authentication information needs to be updated via an Item ERROR webhook. Here's an example of a webhook that is fired when your user's credentials are no longer valid:

{

"webhook_type": "ITEM",

"webhook_code": "ERROR",

"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",

"error": {

"display_message": "The provided credentials were not correct.

Please try again.",

"error_code": "ITEM_LOGIN_REQUIRED",

"error_message": "the provided credentials were not correct",

"error_type": "ITEM_ERROR",

"status": 400

}

}

You make a request to create a public_token

Next, you will need to generate a new public_token for theItem. This can be done by making a request to the/item/public_token/create endpoint and specifying the relevant access_token associated with the Item.

Plaid returns a newly created public_token

In response to your request to create to the /item/public_token/create endpoint, we will return a new public_token for the Item. As a reminder, public_tokens will expire after 30 minutes.

Initialize Plaid Link in your app with the newly created public_token

Now that you have generated a public_token for the Item, you can launch Plaid Link in update mode and specify the new public_token in the token field. When you initialize Plaid Link in update mode, Plaid Link will immediately launch on the credentials pane for the institution associated with theItem.

User re-authenticates with Plaid

Within the Plaid Link pane, your user will provide their updated credentials and any MFA required, and we will verify these updated authentication details.

onSuccess callback indicates that the user successfully re-authenticated

To let you know that your user's Item has successfully re-authenticated, we will fire an onSuccess callback. This callback will be identical to the onSuccess callback that is fired upon initial Item creation. The only difference here is that there is no need to performa any additional token exchange step since the Item's access_token does not change in this process.

Additional technical details on this flow can be found in our API docs .

There are a few steps that must be taken to successfully switch from Plaids Sandbox or Development environment to Plaids Production environment.

If you haven't gotten Production access yet, you must request access to the Plaid Production Environment from your Plaid Dashboard.

Once you have been approved and granted Production access, follow these steps to migrate over:

Change the environment in your Link initialization code : set env to production rather than sandbox or development.

Ensure your API requests are being sent to the right API host: switch from using Sandbox or Development API hosts (sandboxor development) to Production:https://production.plaid.com/.

Use the Production clientsecret key: ensure that you specify your Productionsecretrather than your Sandbox or Developmentsecret. SeeAccount > Keys within your Dashboard to retrieve this key.

You should now be submitting valid Production requests. Note that the Sandbox and Development environments are entirely distinct from the Production environment. AnyItems originally created in Sandbox and Developmentwill need to be created again in Production.

This article is a breakdown of Plaid error codes and our recommendations for how to best handle them.

Requires Client Action

Invalid request errors:

Client sends a malformed request that is missing fields. Please verify that your request body is properly formatted. If the INVALID_REQUEST error is unclear, please refer directly to the Plaid documentation or check out the Plaid Postman Collection for request bodies that you can modify yourself to verify within your own Plaid environment.

Invalid input errors:

Client sends the correct fields but invalid data. Similarly withInvalid request errors, please verify that your request body contains valid Plaid identifiers or access to specific Plaid products. The Plaid documentation details how invalid fields may throw an INVALID_INPUT error type.

Item errors:

ITEM_NO_ERROR

Link was initialized in update mode for an Item that is in a good state. No further action is required. Double check the logic for when you prompt users to reconnect via update mode.

NO_AUTH_ACCOUNTS

Returned from POST /auth/get when there are no valid checking or savings account(s) for which account and routing numbers are provided.Client should prompt end user to connect a different account for `auth`.

PRODUCT_NOT_READY

Returned when a POST request is made for a product whose data pull has not yet finished. Please use webhooks to determine when to fetch new data.

PRODUCT_NOT_SUPPORTED

Returned when a data request has been made for an Item for a product that it does not support. Use the /item/get endpoint to find out which products an Item supports.

Asset Report errors:

PRODUCT_NOT_ENABLED

This means youll need to contact Plaid about enabling your client_id for this product.

Institution errors:

INSTITUTION_NO_LONGER_SUPPORTED

Plaid can no longer provide support for this Item, please prompt your user to connect a different account.

Requires End User Action

INVALID_UPDATED_USERNAME

The username provided in update mode via Link did not match the original username for the Item. You should prompt your user to connect a new account if they have indeed changed their username.

INVALID_CREDENTIALS, INVALID_MFA

Your user entered invalid credentials in Link and should retry.

ITEM_LOGIN_REQUIRED

Launch Link in update mode to enable your user to repair their connection.

ITEM_LOCKED, USER_SETUP_REQUIRED

Your user must contact their bank or log into their online banking portal to resolve.

ITEM_NOT_SUPPORTED, MFA_NOT_SUPPORTED, NO_ACCOUNTS, NO_AUTH_ACCOUNTS

Your user should link a different account because the account they have attempted to link is not supported.

Retryable

Rate limit exceeded:

Plaid uses dynamic rate limits to halt abuse of the Plaid API and to prevent fraud. Clients should limit the number of times they call any Plaid API endpoint for a specific access_token. If your user is encountering a rate limit exceeded error when trying to link their account, we recommend your user retries the following day.

Internal server error:

In general, these errors occur due to an unrecognized response from a financial institution which frequently corresponds to institution downtime. Its reasonable to retry these errors a few hours after failure.

Asset report errors:

DATA_UNAVAILABLE

The causes field will have more detailed information, such as institution down.

ASSET_REPORT_GENERATION_FAILED

Likely due to temporary downtime please prompt your user to retry later.

Institution errors:

INSTITUTION_DOWN, INSTITUTION_NOT_RESPONDING, INSTITUTION_NOT_AVAILABLE

These errors correspond to different types of institution downtime. In general, retrying the following day should be successful.If the problem persists, please reach out to Plaid Support.

When to Expect Errors

This section outlines specific flows where a Plaid error might occur. Note that errors which occur during the Plaid Link flow are received via the onExit callback.

Occurs during initial Item add:

Item errors

"INVALID_CREDENTIALS"

"INVALID_MFA"

"ITEM_LOCKED"

"ITEM_NOT_SUPPORTED"

"MFA_NOT_SUPPORTED"

"NO_ACCOUNTS"

"USER_SETUP_REQUIRED"

Invalid input errors

"INVALID_PUBLIC_TOKEN"

Institution errors

"INSTITUTION_DOWN"

"INSTITUTION_NOT_AVAILABLE"

"INSTITUTION_NOT_RESPONDING"

"INSTITUTION_NO_LONGER_SUPPORTED"

Rate limit errors

"RATE_LIMIT" (this can occur if your user unsuccessfully enters their credentials repeatedly)

Occurs during Link update mode:

Item errors

"INVALID_CREDENTIALS"

"INVALID_MFA"

"INVALID_UPDATED_USERNAME"

"ITEM_LOCKED"

"ITEM_NOT_SUPPORTED"

"ITEM_NO_ERROR"

"MFA_NOT_SUPPORTED"

"NO_ACCOUNTS"

"USER_SETUP_REQUIRED"

Invalid input errors

"INVALID_PUBLIC_TOKEN"

Institution errors

"INSTITUTION_DOWN"

"INSTITUTION_NOT_AVAILABLE"

"INSTITUTION_NOT_RESPONDING"

"INSTITUTION_NO_LONGER_SUPPORTED"

Occurs in response to API calls:

Item errors

"NO_AUTH_ACCOUNTS"

"PRODUCTS_NOT_SUPPORTED"

"PRODUCT_NOT_READY"

ITEM_LOGIN_REQUIRED

Invalid request errors

"INVALID_BODY"

"INVALID_FIELD"

"INVALID_HEADERS"

"MISSING_FIELDS"

"NOT_FOUND"

"SANDBOX_ONLY"

"UNKNOWN_FIELDS"

Invalid input errors

"INVALID_ACCESS_TOKEN"

"INVALID_ACCOUNT_ID"

"INVALID_API_KEYS"

"INVALID_INSTITUTION"

"INVALID_PRODUCT"

"INVALID_PUBLIC_TOKEN"

"UNAUTHORIZED_ENVIRONMENT"

Rate limit exceeded errors

"AUTH_LIMIT"

"IDENTITY_LIMIT"

"ITEM_GET_LIMIT"

"RATE_LIMIT"

"TRANSACTIONS_LIMIT"

API errors

"INTERNAL_SERVER_ERROR"

"PLANNED_MAINTENANCE"

Asset Report errors (can only occur if you are using the Assets endpoints)

"ASSET_REPORT_GENERATION_FAILED"

"DATA_UNAVAILABLE"

"INVALID_PARENT"

"PRODUCT_NOT_ENABLED"

"PRODUCT_NOT_READY"

Institution errors

"INSTITUTION_DOWN"

"INSTITUTION_NOT_AVAILABLE"

"INSTITUTION_NOT_RESPONDING"

"INSTITUTION_NO_LONGER_SUPPORTED"

Webhooks enable you to set up integrations that subscribe to certain events from Plaid. When one of those events is triggered such as the completion of a historical transaction pull Plaid should send a POST payload with raw JSON to your webhook URL from one of the following IP addresses:

52.21.26.131

52.21.47.157

52.41.247.19

52.88.82.239

Note that these IPs are subject to change.

If Plaid receives a non-200 response or no response within 10 seconds from your webhook endpoint, we will retry sending the webhook up to two times with a few minutes in between each webhook. The webhook's URL is set by the optionalwebhook parameterwhen creating an Item in Plaid Link. Any valid URL can be used as a webhook. An HTTPS URL must have a valid SSL certificate. Please refer to our documentation for a list of possible webhooks.

If you have admin access within your Plaid Dashboard account, you can add other teammates to your account and assign different permissions to each teammate as necessary.

Adding or removing a teammateYou can add additional teammates to your Plaid team from the Team Settings > Members menu within yourPlaid Dashboard. Conversely, you may also remove teammates from the Members menu.

General permissionsYou can assign specific permissions to each teammate that you add to your Plaid account:

Support: users have view access to the Usage page, the Activity menus (Usage, Status, and Logs), and the Support tab for filing support tickets

Admin access: users can request access to other environments, file support tickets, customize Plaid Link, add and manage other teammates, and view all API secrets

API secrets accessAPI key access can control the following:

Production: users with Production access can view and rotate your Production secret

Development: users with Development access can view and rotate your Development secret

Sandbox: users with Sandbox access can view and rotate your Sandbox secret

What is two-factor authentication?

Two-factor authentication is an extra layer of security designed to make sure youre the only person who can access your Dashboard account. In addition to your password, two-factor authentication requires you enter an authentication code sent to you to verify your identity.

How can I enable two-factor authentication?

Head to the Account > Security section of your Dashboard and follow the instructions to turn on two-factor authentication. Youll be prompted to select an authentication method to use during sign-in. We support authentication viaSMS oran authentication app such as Google Authenticator or Authy. Team page

What happens if I lose my mobile device?

When you enable two-factor authentication, well provide you with a backup recovery codeto access your Dashboard account in the event that youdon'thave access to your mobile device. Be sure to write down the recovery code and store it in a safe place since we'll only display it once during the setup process.

How can I see if my teammates have enabled two-factor authentication?

Each team members two-factor authentication status will be displayed on your .

Once I turn on two-factor authentication, when am I required to enter my code?

After you enable two-factor authentication, youll be prompted to enter an authentication code each time you sign in.

Can I disable two-factor authentication after turning it on?

Yes, youll be able to disable two-factor authentication at any time.

Which country codes are supported for the SMS authentication option?

We support phone numbers from the following countries. Please note that even if your country is in this list, we cannot guarantee deliverability.

Expand to show list of countries

Afghanistan (+93) Albania (+355) American Samoa (+1684) Andorra (+376) Angola (+244) Anguilla (+1264) Antigua and Barbuda (+1268) Argentina (+54) Armenia (+374) Aruba (+297) Ascension (+247) Australia/Cocos/Christmas Island (+61) Austria (+43) Azerbaijan (+994) Bahamas (+1) Bahrain (+973) Bangladesh (+880) Barbados (+1246) Belarus (+375) Belgium (+32) Belize (+501) Benin (+229) Bermuda (+1441) Bhutan (+975) Bolivia (+591) Bosnia and Herzegovina (+387) Botswana (+267) Brazil (+55) Brunei (+673) Bulgaria (+359) Burkina Faso (+226) Burundi (+257) Cambodia (+855) Cameroon (+237) Canada (+1) Canary Islands (+3491) Canary Islands (+3491) Cape Verde (+238) Cayman Islands (+1345) Central Africa (+236) Chad (+235) Chile (+56) China (+86) Colombia (+57) Comoros (+269) Congo (+242) Congo, Dem Rep (+243) Cook Islands (+682) Costa Rica (+506) Croatia (+385) Cuba (+53) Cyprus (+357) Czech Republic (+420) Denmark (+45) Djibouti (+253) Dominica (+1767) Dominican Republic (+1809201) East Timor (+670) Ecuador (+593) Egypt (+20) El Salvador (+503) Equatorial Guinea (+240) Eritrea (+291) Estonia (+372) Ethiopia (+251) Falkland Islands (+500) Faroe Islands (+298) Fiji (+679) Finland/Aland Islands (+358) France (+33) French Guiana (+594) French Polynesia (+689) Gabon (+241) Gambia (+220) Georgia (+995) Germany (+49) Ghana (+233) Gibraltar (+350) Greece (+30) Greenland (+299) Grenada (+1473) Guadeloupe (+590) Guam (+1671) Guam (+1671) Guatemala (+502) Guinea (+224) Guinea-Bissau (+245) Guyana (+592) Haiti (+509) Honduras (+504) Hong Kong (+852) Hungary (+36) Iceland (+354) India (+91) Indonesia (+62) Iran (+98) Iraq (+964) Ireland (+353) Israel (+972) Italy (+39) Ivory Coast (+225) Jamaica (+1876) Japan (+81) Jordan (+962) Kenya (+254) Korea Dem People's Rep (+850) Korea Republic of (+82) Kosovo (+883) Kuwait (+965) Kyrgyzstan (+996) Laos PDR (+856) Latvia (+371) Lebanon (+961) Lesotho (+266) Liberia (+231) Libya (+218) Liechtenstein (+423) Lithuania (+370) Luxembourg (+352) Macau (+853) Macedonia (+389) Madagascar (+261) Malawi (+265) Malaysia (+60) Maldives (+960) Mali (+223) Malta (+356) Marshall Islands (+692) Martinique (+596) Mauritania (+222) Mauritius (+230) Mexico (+52) Micronesia (+691) Moldova (+373) Monaco (+377) Mongolia (+976) Montenegro (+382) Montserrat (+1664) Morocco/Western Sahara (+212) Mozambique (+258) Myanmar (+95) Namibia (+264) Nepal (+977) Netherlands (+31) Netherlands Antilles (+599) New Caledonia (+687) New Zealand (+64) Nicaragua (+505) Niger (+227) Nigeria (+234) Northern Mariana Islands (+1670) Norway (+47) Oman (+968) Pakistan (+92) Palau (+680) Palestinian Territory (+970) Panama (+507) Papua New Guinea (+675) Paraguay (+595) Peru (+51) Philippines (+63) Poland (+48) Portugal (+351) Puerto Rico (+1787) Qatar (+974) Reunion/Mayotte (+262) Romania (+40) Russia/Kazakhstan (+7) Rwanda (+250) Samoa (+685) San Marino (+378) Sao Tome and Principe (+239) Saudi Arabia (+966) Senegal (+221) Serbia (+381) Seychelles (+248) Sierra Leone (+232) Singapore (+65) Slovakia (+421) Slovenia (+386) Solomon Islands (+677) Somalia (+252) South Africa (+27) South Sudan (+211) Spain (+34) Spain (+34) Sri Lanka (+94) St Kitts and Nevis (+1869) St Lucia (+1758) St Pierre and Miquelon (+508) St Vincent Grenadines (+1784) Sudan (+249) Suriname (+597) Swaziland (+268) Sweden (+46) Switzerland (+41) Syria (+963) Taiwan (+886) Tajikistan (+992) Tanzania (+255) Thailand (+66) Togo (+228) Tonga (+676) Trinidad and Tobago (+1868) Tunisia (+216) Turkey (+90) Turkish Republic of Northern Cyprus (+90) Turkmenistan (+993) Turks and Caicos Islands (+1649) Tuvalu (+688) Uganda (+256) Ukraine (+380) United Arab Emirates (+971) United Kingdom (+44) United States (+1) Uruguay (+598) Uzbekistan (+998) Vanuatu (+678) Vatican City (+379) Venezuela (+58) Vietnam (+84) Virgin Islands, British (+1284) Virgin Islands, U.S. (+1340) Yemen (+967) Zambia (+260) Zimbabwe (+263)

Plaid has three different environments: Sandbox, Development, and Production. Each environment is hosted separately, and data does not flow between environments.

Sandbox Our Sandbox environment,https://sandbox.plaid.com, is available to you as soon as you create your Plaid account. Sandbox provides test Items that can be generated using test credentials. You can generate an unlimited number of these testItemsto support your building phase.

Development In order to access our Development environment,https://development.plaid.com, you will have to file a request via the Dashboard. Once your access has been granted, you will be able to add up to 100 liveItemsto the Development environment. Keep in mind that anyItemscreated in Development cannot be moved to Production at any point. We recommend using Development for testing liveItemsonly.

Production Our Production environment,https://production.plaid.com, is where all your live, production traffic should take place. Once you're ready to gain Production access, reach out to our Sales team. They will be in touch to walk you through the necessary compliance steps.

Note: "Link with account numbers" is only supported by these country codes when initializing Plaid Link : US, CA

The following are the steps required to enable all Auth features:

Update Plaid Link configuration

By default, only Instant Auth is enabled for your Plaid account.Please reach out to your account manager to get started. If you are not yet a Plaid customer, please contact our sales team to learn more.

To link via Instant Match,you mustinclude auth as one of the products when initializing Plaid Link.

To link via Automated Microdeposits,you mustinclude auth as one of the products when initializing Plaid Link andyou mustinclude theuser object field (see documentation )in your Plaid Link initialization

To link viaSame Day Microdeposits, you mustinclude theuser object field in your Plaid Link initialization and youmust include auth as the only product.

Handle and consume the metadata.accounts.verification_status object in the onSuccess() callback so that you can track the status to determine when to call /auth/get.

Implement verification flow for Same Day Microdeposits

Build a user interface for your users to verify accounts. Youll need to prompt your user to verify when the deposits hit their account in 2-3 business days and launch Plaid Link in verification mode so that they can enter those amounts.

To allow your user to verify, generate a new public_token for that users access_token and initialize Plaid Link in verification mode.

Implement Auth webhooks for Automated Microdeposits

Test your Auth integration in the Sandbox

Plaid bills for events that occur in our Production environment only.

For our Auth, Balance, Transactions, Identity, and Income products, Plaid bills based onItemsthat were successfully created in our Production environment. A successful creation is indicated by Plaid returningan access_token in response to requests made to the /item/public_token/exchange endpoint.

The specific billing event for eachItem is based on the products it has accessed. These products fall into one of three categories:

One-timefee endpoints: Using an access_token to access Auth, Identity, or Income incurs a one-time fee, charged either when an Item is createdaccording to the productsfor which Link is initialized or when an access_tokenis firstused to access one of those products endpoints. Subsequent requests to these products' endpointsshouldnot incur further fees.

Per-request endpoint: Eachsuccessful requestto the Balance endpoint incurs a fee.

Monthlyfee endpoint: Items thatweresuccessfully created with Transactions as a product, or used in a request to the Transactions endpoint (thereby adding Transactions toan Item's billed products), incur a monthly fee.Itemsthat have since entered a state wheredata cannot be retrieveditems in error or that need to be updated will continue to be billed. Note thata deletedItem will lastbebilled for the month in which is was deleted. For example, an Item deleted on January 1st will be included in January's bill, which you will receive in the beginning of February, but not inFebruary's bill, which you will receive in the beginning of March.

These are general billing guidelines for Plaid's Growth pricing tier. Please refer to your Services Agreement for specific billing terms.

Plaid sends a TRANSACTIONS_REMOVED webhook when pending or posted transactions have been removed from our system. Pending transactions can be removed for two reasons: 1) They were matched to a posted transaction; 2) They no longer appear in the data we get from the institution, which may occur when transactions are cancelled by the bank or payment processor. Posted transactions are removed from our system when the transaction was removed by the institution. You will receive a TRANSACTIONS_REMOVEDwebhook with the transaction_ids for each removed transaction, whether it was pending or posted.

{

"webhook_type": "TRANSACTIONS",

"webhook_code": "TRANSACTIONS_REMOVED",

"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",

"removed_transactions": ["yBVBEwrPyJs8GvR77N7QTxnGg6wG74H7dEDN6", "kgygNvAVPzSX9KkddNdWHaVGRVex1MHm3k9no"],

"error": null

}

Future /transactions/get requests will not return these removed transactions.

You can receive notifications regarding transactions from Plaid via webhooks when the following occurs:

an initial transaction pull has completed

new transactions are associated with anItem

transactions have been removed from anItem

an historical transaction pull has completed

INITIAL_UPDATE

Plaid fires the INITIAL_UPDATE webhook when an Item'sinitial transaction pull has finished.

ExampleINITIAL_UPDATE webhook:

{

"webhook_type": "TRANSACTIONS",

"webhook_code": "INITIAL_UPDATE",

"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",

"error": null,

"new_transactions": 19

}

The initial transaction pull occurs when creating an Item with Transactions specifically, when Plaid Link'sproduct array is initialized with'transactions'. If an Item was not initialized with 'transactions' as a product and is later used to make a /transactions/get request, you will be returned a PRODUCT_NOT_READY error, but theINITIAL_UPDATE and HISTORICAL_UPDATE webhooks will fire shortly thereafter.

HISTORICAL_UPDATE

After the initial transaction pull is finished, Plaid will begin the historical transaction pull. Plaid fires the HISTORICAL_UPDATE webhook when the historical transaction pull for an Item is finished.

ExampleHISTORICAL_UPDATEwebhook:

{

"webhook_type": "TRANSACTIONS",

"webhook_code": "HISTORICAL_UPDATE",

"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",

"error": null,

"new_transactions": 231

}

The length of time required for a historical pull is determined by the volumeof an Item'saccounts and transactions. AnItem with a large number of accounts such as a business bank account with many credit cards, each of which has many transactions per day will take longer than an account with one or two accounts with few transactions per day.

The historical transaction pull retrieves as much historical data as is available for the Itemat the financial institution.

DEFAULT_UPDATE

TheDEFAULT_UPDATE webhook is fired whenPlaidfetches new pending or posted transactionsfor an Item.

ExampleDEFAULT_UPDATEwebhook:

{

"webhook_type": "TRANSACTIONS",

"webhook_code": "DEFAULT_UPDATE",

"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",

"error": null,

"new_transactions": 3

}

Plaid routinely checksfor transaction updates, but a DEFAULT_UPDATE will only fire when new transaction data is available. When aDEFAULT_UPDATEwebhook is triggered, you may make a /transactions/get request to retrieve the latest transaction data.Please note that the regularity of transaction data updates can vary across financial institutions.

TRANSACTIONS_REMOVED

Plaid sends aTRANSACTIONS_REMOVED webhook when pending or posted transactions have been removed from our system.

ExampleTRANSACTIONS_REMOVEDwebhook:

{

"webhook_type": "TRANSACTIONS",

"webhook_code": "TRANSACTIONS_REMOVED",

"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",

"removed_transactions": ["yBVBEwrPyJs8GvR77N7QTxnGg6wG74H7dEDN6", "kgygNvAVPzSX9KkddNdWHaVGRVex1MHm3k9no"],

"error": null

}

Pending transactions can be removed for the following reasons:

They were matched to a posted transaction.

They no longer appear in the data we get from the institution, which may occur when transactions are cancelled by the bank or payment processor.

To learn more about pending transactions, see the Pending transaction overview.

Posted transactions are removed from Plaid's system when the transaction was removed by the institution.

You will receive a TRANSACTIONS_REMOVEDwebhook with the transaction_ids for each removed transaction. Future /transactions/get requests will not return previously removed transactions.

If you wish to reset your password, navigate to the Dashboard login page and select Reset Password.

Plaid Dashboard

On the Reset your password page, enter your email address and select Reset password. Plaid will then email you instructions for resetting your password.

If you are not receiving aReset your password email, then your Plaid Dashboard account is probably unverified. Check your inbox for an emailfrom [email protected] the subject "Confirm your email":

If you cannot find the above email in your inbox, please login to the and selectClick here to resend it:

If you are unable to login to verify your Dashboard account because you have forgotten your password, please contact your Sales or Growth representative for assistance.

This article outlines how to simulate MFA and error flows within Plaid Link. This must be done within the Sandbox environment.

Simulating MFA

You can simulate the various MFA flows within Plaid Link by using the following passwords in conjunction with the Sandbox username, user_good:

mfa_device: simulate a device MFA flow, such as a code that is sent to your user's phone via SMS

mfa_questions_<n>_<m>: simulate a questions-based MFA flow you can control the number of rounds and questions your user must answer by adjusting the n and m values, respectively

mfa_selections: simulate a selections-based MFA flow where your user is asked a single security question and given several answer options to select from

mfa_selections_<n>_<m>_<o>: simulate a multiple-selections MFA flow where your user is asked multiple security questions and given several answer options to select from for each question. The number of rounds, questions, and answer options can be controlled by adjusting the n, m, and o values, respectively.

Simulating errors

You can simulate anITEM_ERROR or INSTITUTION_ERROR that your user could encounter during the Plaid Link flow. To do so, modify the password accordingly:

error_[ERROR_CODE]

For example, if you want to simulate an INVALID_CREDENTIALS error, you must use the following password: error_INVALID_CREDENTIALS

Within Link, you can enable an account selection pane, which allows a user to select one or more of the account(s) at their institution. When enabled, this pane will display once the user has successfully authenticated and is the final step of the Link flow.

Dashboard

Although a user may only select some of the accounts associated with their institution, our API will still provide access to account data for all of their available accounts at the institution. Note:there's an exception for Items created via Auth'sAutomated Micro-depositsandSame Day Micro-deposits flows; the API will only provide account data for the selected account.

We will provide information on which account(s) a user selected in this pane in the accounts object of the onSuccess callback.

You can enable this pane through your .

The number of retrievable transactions is limited by the amount of transaction data available from an institution. By default, the amount of transactions returned per call to /transactions/get will be less than or equal to 100 transactions. This can be modified via the count parameter to a maximum of 500. Use the count and offset parameters to paginate the results when receiving a large number of transactions. After an item has accessed Transactions and received initial and historical pull responses, subsequent requests to /transactions/get should usestart_date and end_dateto set a ten day date bound. /transactions/get is heavily rate limited, and this date bound will ensure successful requests.

curl -X POST https://sandbox.plaid.com/transactions/get \

-H 'content-type: application/json' \

-d '{

"client_id": String,

"secret": String,

"access_token": String,

"start_date": "2017-03-01",

"end_date": "2017-03-11",

"options": {

"count": 250,

"offset": 100

}

}'

This article outlines some common issues that an end-user may run into with MFA in Plaid Link and recommended troubleshooting steps for these issues.

User not receiving MFA code

Plaid supports one-time MFA access codes for a select number of institutions. These institutions will send an access code via SMS or email, and these codes must be entered in Plaid Link to complete the authentication process.

If a user does not receive the access code, most likely, the contact information their institution has on file is outdated. To resolve this, instruct them to check the phone number and email on file with their institution and have them update these details if needed. Once their contact information has been updated, have them go through the Plaid Link flow again. If the code continues to fail to send, please open a case through the Plaid Dashboard.

MFA_NOT_SUPPORTEDerrors

AnMFA_NOT_SUPPORTEDerror is returned when an institution requires a form of MFA that Plaid does not support. Users with unsupported MFA are rare, and we are continually working to support all possible MFA types.

Once youhave sent requests in Development or Production with a live, non- Sandbox access_token, you will start seeing usage data in your Dashboard : The following data can be found within your Dashboard's Usage tab:

Total connected Items

Item adds and removes over time

Breakdown of usage per product.

More usage-tracking tools will be added to the Dashboard, so check back here for updates!

Overview

Your Plaid Dashboard account can create or join multiple teams to enable collaboration across different teams or companies.

From the Plaid Dashboard you can do the following:

Create multiple teams (each with their own individual API keys)

Join multiple teams from one Plaid account

Add or remove members to individual teams (with necessary Admin permissions)

Switch between teams

Creating a new team

At the top-left of your Plaid Dashboard, click the team name drop-down and select Create new team:

Deactivate my account

Once you have submitted your team name and purpose into the form, click Create team.Your new team will come with a fresh set of API keys which can be used to build a new Plaid integration.

Team settings

Click the Settings drop-down in your Plaid Dashboard to view your team information, API keys, API version, team members, and third-party integrations:

Please note that specific permissions are required to view webhook and billing settings.

Profile settings

You can create a new team, view your existing teams, and leave a team from your Profile settings found at the top-right of your Plaid Dashboard:

Additional information

All new teams must be approved to receive Development and Production environment access.

Billable usage will be separate across all teams.

If you are the last team member to leave a team, you will receive the following error:

Cannot remove the last admin user from the team

You cannot leave a team if you are the last member in the team. In this case, please file a support case if you wish to deactivate your team.

Every Plaid API response includes a request_id as the 'X-Request-Id' header. The request_id is included regardless of whether or not the API request succeeded or failed.

Example response header from a request to the Plaid API:

< HTTP/1.1 200 OK

< Content-Type: application/json; charset=utf-8

< Server: nginx

< X-Request-Id: a2d7b95be32b47a08c0912e000c1c730

Please include the request_id ('X-Request-Id' header) or if using Link, the link_session_id and request_id when creating a Dashboard case.

Plaid and Dwolla have partnered to offer businesses a solution for ACH payments. Users are able to quickly and securely verify bank account ownership using Plaid, and then send payments with Dwollas ACH API.

With the Plaid + Dwolla integration, your users can connect their account in seconds by simply inputting their banking credentials in Plaids front-end module. Once a user authenticates their bank account through Plaid, you will receive a token that can be used for creating a funding source for payments via Dwollas API.

Plaids mobile-friendly module handles input validation, error handling, and multi-factor authentication, providing a seamless experience that helps convert more users for your business.

Getting Started

First, you will need to set up your Plaid account to ensure that its enabled for the integration with Dwolla. Your Plaid account will need to be enabled for the Sandbox environment to be able to get the full experience in the Dwolla Sandbox, and you must be enabled for Plaid Production to access the Dwolla Production environment.

To learn more about how Plaid and Dwolla can help you create an ideal payment experience for your users, read our blog post or check out our integration documentation here.

Transactions should bemarked "pending": truewhen they have been labeled as such by the institution. Transactions shouldbe marked "pending": falsewhen theyhave settled and posted.

When a pending transaction is converted to a posted transaction, Plaid removesthe pending transaction, sends a TRANSACTIONS_REMOVED webhook, and returns the transactions new, posted transaction. The posted transaction shouldhave a pending_transaction_id field, whose value is the transaction_id of the now-removedpending transaction.

It is worth noting thatthepending and posted versions of a transaction may not necessarily share the same details: their nameandamount may change to reflect tips and other updates. Pending transactions are short-lived andfrequentlyaltered or removed by the institution before finally settling as a posted transaction. In some rare cases, it is not possible to match a posted transaction to its pending counterpart. On such occasions, the posted transaction will bereturned without a pending_transaction_id field,and its pending transactionis removed.

Pending transactions are returned when possible, but are not available for all institutions.

Plaid Link is a drop-in module that enables you to createItems, which may be used to access Plaids products: Auth for ACH payment, Transactions for transaction data, Identity for identity information, Balance for real-time balance checks, and Income for income and employer data. Plaid Link guides users throughcredential validation, multi-factor authentication, and error-handling, all without leaving your application flow. Thisreduces friction and increases conversions.

To see Plaid Link in action, check out our Plaid Link Demo, andfor a step-by-step implementation guide, please refer to the Plaid Link documentation.

The Plaid + Stripe integration can be leveraged for institutions that support Plaid's Auth product. Use the /institutions/get endpoint to retrieve supported institutions, and the /institutions/search endpoint to retrieve which products are supported for a given institution.Specifically, theproducts field will show whether Auth is supported. If so, the institution is compatible with the integration. Example /institutions/searchresponse:

{

"institutions": [

{

"credentials": [

{

"label": "User ID",

"name": "username",

"type": "text"

},

{

"label": "Password",

"name": "password",

"type": "password"

}

],

"has_mfa": true,

"institution_id": "ins_109509",

"mfa": [

"code",

"list",

"questions",

"selections"

],

"name": "First Gingham Credit Union",

"products": [

"balance",

"credit_details",

"auth",

"info",

"numbers",

"transactions"

]

},

...

],

"request_id": "DLVvK"

}

Plaid endeavors to pull as much transaction history as possible, up to 24 months, but data availability will vary by institution.

A request to Plaids Transactions product will return atransactions object: Request

curl -X POST https://sandbox.plaid.com/transactions/get \

-H 'content-type: application/json' \

-d '{

"client_id": String,

"secret": String,

"access_token": String,

"start_date": "2017-01-01",

"end_date": "2017-02-01",

"options": {

"count": 250,

"offset": 100

}

}'

Response

"transactions": [

{

"account_id": "vokyE5Rn6vHKqDLRXEn5fne7LwbKPLIXGK98d",

"amount": -500,

"category": null,

"category_id": null,

"date": "2017-01-29",

"location": {Object},

"name": "United Airlines",

"payment_meta": {Object},

"pending": false,

"pending_transaction_id": null,

"transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",

"transaction_type": "special"

}

]

Theaccount_id field identifies the account to which the transaction belongs. A request to Plaids Accounts product will return anaccountsobject with information about an items accounts: Request

curl -X POST https://sandbox.plaid.com/accounts/get \

-H 'content-type: application/json' \

-d '{

"client_id": String,

"secret": String,

"access_token": String

}'

Response

"accounts": [

{

"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",

"balances": {

"available": 100,

"current": 110,

"limit": null

},

"mask": "0000",

"name": "Plaid Checking",

"official_name": "Plaid Gold Standard 0% Interest Checking",

"subtype": "checking",

"type": "depository"

},

{

"account_id": "6Myq63K1KDSe3lBwp7K1fnEbNGLV4nSxalVdW",

"balances": {

"available": null,

"current": 410,

"limit": 2000

},

"mask": "3333",

"name": "Plaid Credit Card",

"official_name": "Plaid Diamond 12.5% APR Interest Credit Card",

"subtype": "credit",

"type": "credit"

},

...

]

The account_ids in a transactions response correspond to the account_ids in an accounts response, enabling you to map a transaction to an account.

A transaction with a negative amount represents money flowing into the account, such as a direct deposit. A transaction with a positive amount represents money flowing out of the account, such as a purchase. For more information about the data fields returned for accounts and transactions, please see the data overview.

Plaid returns currency values in the currency used by the financial institution for that account. For example, a Canadian institution may return currency values in CAD; a BitCoin account may return currency values in BTC. Example account response:

http code 200

{

"accounts": [{

"account_id": "vokyE5Rn6vHKqDLRXEn5fne7LwbKPLIXGK98d",

"balances": {

"available": 129.99,

"current": 129.99,

"limit": null

},

"mask": "1111",

"name": "Savings",

"official_name": "Savings",

"subtype": "savings",

"type": "depository"

},

{

"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",

"balances": {

"available": 0.7,

"current": 0.7,

"limit": null

},

"mask": "fccd",

"name": "BTC Wallet",

"official_name": "BTC Wallet",

"subtype": "other",

"type": "other"

}],

"item": {Object},

"request_id": "45QSn"

}

The Plaid + Stripe integration combines Stripe's ACH processor with Plaid's Auth product. When a Plaid public_token is created, you'll incur a one-time fee from Plaid. See our Pricing page for more pricing information, and refer to your Services Agreement for specific billing terms. To use the stripe_bank_account_token to facilitate ACH transfers, you'll need to work with Stripe as your payment processor. Stripe has its own service and billing requirements, and questions about Stripe's service or billing should be directed to Stripe Support. Find billing information for Plaid's other products on our Billing overview.

A unique Item is created when an end-user links their bank account through Plaid. Based on howyou'veset up your integration, it might be possible for an end-user to create multiple Items for the same set of online banking credentials. Depending on your applications use case, you may want to prevent an end-user from creating multiple Items. Below are some reasons why you might want to prevent that:

Development environment : exhausting all of your 100 live credentials may result in an ADDITION_LIMIT error.

Billed for duplicateItems: if an end-user has already linked their bank account and created an Item in your application, you may not want the same end-user to create a new Item because this can affect your billable usage in Production.

Every application serves a different purpose, so please consider what is necessary for your use case - below are some suggestions for how you may implement this logic in your application:

User Login

Position the Plaid Link flow behind your applications user-login. This enables you to store information about which bank(s) your user has already connected via Plaid Link.

onSuccess()callback

Detect whether an incoming end-user is creating a duplicate Item by leveraging the onSuccess() callback. TheonSuccess() callback will contain bank account metadata that you can use to verify whether the end-user has already connected to your application. You can use the account information in onSuccess()s metadata to validate whether the end-user has already connected the relevant accounts. Specifically, you can compare a combination of the accounts institution_id, account name, and account mask to determine whether your end-user has previously linked their account to your application. Other fields found within the Account schema may also be useful to your integration.

It is important to note that theItem has not been created until you have exchanged the public_token from theonSuccess() callback for anaccess_token. A billing event is only initiated once you have successfully completed the Exchange Token flow for anaccess_token.

Plaid Pattern

The Plaid Pattern example application has implemented server logic that checks whether the user ID and institution ID pair already exist in the application database - you may examine the example source code here.

An initial pull occurs when an item first accesses the Transactions product. By default, Plaidpulls the item'slast 30 days of transactions. On average, thistakes between30 seconds to two minutes. After the initial pull, Plaid begins the historical pull, pulling all available transactions. The historical pull typically takes three to fiveminutes, but may take longer, depending onthe number of accounts andtransactions associated with the item.

The completion of either pull shouldtrigger a webhook.When an initial pull has finished, Plaid will send an INITIAL_UPDATE webhook, and when the historical pull has finished, Plaid will send a HISTORICAL_UPDATE webhook. See our webhook articles for more information.

This article offers suggestions on how to utilize onEvent callbacks to track user behavior within Plaid Link.

TheonEvent callback is called throughout multiple points within the Plaid Link flow. This callback has an eventName parameter, which describes the event that occurred within Plaid Link, and a metadata parameter, which includes additional details for each event.

The key events to track for analysis purposes are the OPEN, TRANSITION_VIEW, ERROR, EXIT, andHANDOFF events.

OPEN: the onEvent callback will be fired with the OPEN event when your user first launches Plaid Link. Tracking this event will allow you to capture how many of your users opt-in to the Plaid Link flow.

TRANSITION_VIEW: the TRANSITION_VIEW event occurs when your user transitions from one pane in Plaid Link to the next. The metadata object associated with the TRANSITION_VIEW event provides details on the exact pane your user has transitioned to in the view_name field. For example, if your user just moved to the credentials pane after selecting their institution, the metadata object would return CREDENTIALS in the view_name field.

EXIT: the EXIT event occurs when your user exits from Plaid Link without successfully completing the flow.

ERROR: the ERROR event occurs when your user runs into a recoverable error within Plaid Link. The metadata object will provide details on the specific error your user encountered.

HANDOFF: theHANDOFF event occurs when your user successfully links their account by completing the Plaid Link flow.

Additionally, please refer to the metadata reference to see all of the fields that can be utilized for your analytics.

Depending on what metrics are most valuable to your business, you can utilize the above events to analyze user behavior within Plaid Link. For example, many customers will track the OPEN to HANDOFF rate to understand how many users successfully link their account after entering Plaid Link. If you have any additional questions, please ask your account manager so that we can aid you with each step of the Plaid Link flow to ensure you are gathering the right analytics for your business.

Missing transactions

Transaction data quality

Missing accounts

Misclassified accounts

Transactions

You may occasionally notice that a user appears to be missing transactions or that some aspect of the transactions data is incorrect. These issues sometimes occur on a one-off basis for users. If you observe ten or more access_tokens with missing data over a 48-hour period for a given institution, see our guide.

Missing transactions

If a user is missing transactions in a given date range, please follow these steps:

Wait 48 hours, and attempt a /transactions/get request for the date range in which transactions are missing.It is possible that the institution is delayed in processing the transaction.

If the transactions are still missing, file a case in the Dashboard under Missing data issues >Missing transaction data, and include the following information:

A general description of the problem

The date, amount, and/ormerchant name of one or more of the missing transactions

This data will help our Support team investigate as quickly as possible and enable us to confirm if we have fixed the issue. Example:

Subject: Lucky Dog Bank Token Missing November Transactions

An access_token for Lucky Dog Bank is missing transactions from 11/1/16 onward.

The most recent transaction was a purchase on 11/20/16, from Amazon, for $120.25

Transaction data quality

If a transaction is returning unexpected datasuch as an incorrect name or categoryplease file a case in the Dashboard underFaulty data issues >Incorrect transaction data, and include the following information:

A general description of the problem, such as the expected value(s) and the value(s) being returned

Transaction _id(s)

This data will help our Support team investigate as quickly as possible and enable us to confirm if we have fixed the issue. Example:

Subject: Lucky Dog Bank Misclassifying Wine Bar as Winery

An access_token for Lucky Dog Bank is returning transactions that have incorrect an transaction categorys. Transaction _id: 600r0LrVvViXjq96lBpdtyOWboBvzmsaZoeaV is being categorized as a Beer, Wine and Spirits shop, but should be categorized as a Food and Drink winery.

Accounts

You may occasionally notice that a user appears to be missing an account, or that some aspect of the accounts data is incorrect. These issues sometimes occur on a one-off basis for usersif you are observing ten or more accounts with missing data over a 48-hour period for a given institution, see our widespread institution issues page. Because these issues are generally specific to an institution, please submit cases on behalf of one institution at a time. This will enable us to work through them as quickly as possible!

Missing accounts

If one or more accounts are not being returned, please follow these steps:

Verify that the user has not closed the account.

Check to see if a replacement account_id was issued for the account. If so, it is expected that the original account_id would no longer be returned.

If the account has not been closed or replaced, please file a case in the Dashboard underMissing data issues >Missing account data, and include the following information:

A general description of the problem and how many access_token(s) are affected

Affected access_token(s)

The type of account missing and its last four digits

This data will help our Support team investigate as quickly as possible and enable us to confirm if we have fixed the issue. Example:

Subject: Lucky Dog Bank missing second depository account

An access_token for Lucky Dog Bank is failing to return one of its two checking accounts.

Access_token: d209f3be058d4c6cb6620037e7bef254d209f3be058d4c6cb6620037e7bef254d209f3be058d4c6cb6620037e7bef254d209f3be058d4c6cb6620037e7bef254

Missing account type: checking Last four digits of missing account: 4200

Misclassified accounts

If an account has the incorrect typee.g., a depository account is being classified as a certificate of deposit accountplease file a case in the Dashboard under Faulty data issues >Incorrect account data, and include the following information:

A general description of the problem and the number of affected access_token(s)

Affected access_token(s)

account_id(s) of the misclassified account(s)

The type or subtype that the account should be.

This data will help our Support team investigate as quickly as possible and enable us to confirm if we have fixed the issue. Example:

Subject: Lucky Dog Bank Misclassifying credit accounts as depository

An access_token for Lucky Dog Bank is misclassifying a credit account as a depository account.

Access_token: d209f3be058d4c6cb6620037e7bef254d209f3be058d4c6cb6620037e7bef254d209f3be058d4c6cb6620037e7bef254d209f3be058d4c6cb6620037e7bef254

Account _id of misclassified account: YzzrzBrO9OSzo6BXwAvVuL5dmMKMqkhOoEqeo Account type should be depository, but is being returned as credit

WithPlaid Link and Stripe, your users can securelylink their bank accounts withoutenteringaccount and routing numbers or waiting for micro-deposits. Once they authenticate throughPlaid, you will receive a token thatcanbe used for payments via Stripes ACH API.

Getting Started

First, configure your Stripe account to acceptACH transfers and sign up for a Plaid account. Afterwards, head to the Integrations page in your Plaid Dashboard and clickConnect with Stripe:

Link and Stripe documentation

To learn more about how Plaid and Stripe can help you create seamless payment experiences, read more on our blog post and check out our.

Storage

An access_token is your key to retrieving data on behalf of an item,a set of credentials at a financial institution. access_tokens are obtained by exchanging a public_token, which you receive from Plaid Link, via the /item/public_token/exchange endpoint. A public_token expires after 30 minutes and is usable only once;after it has been exchanged for an access_token (or used to initialize Link in update mode ), it will no longer be valid. Thus, the public_token does not need to be stored after it is used. An access_token, however, does not expire, and it should be securely stored. For security reasons, you may rotate an access_token, which invalidates it and returns a new access_token. This new access_token can be used to make requests on behalf of the item to which the original access_token corresponded.

For security reasons, Plaid does not offer an endpoint that returns a list of your items or access_tokens.

Removal

See the our articleAccess_token and Item FAQ > How do I remove an item.

What Are Plaid's products?

How many banks does Plaid support?

What type of information does Plaid provide via Transactions?

How often do you pull transaction data?

How much does Plaid cost?

Can I test Plaid's data and products?

Once I've tested Plaid, how do I upgrade to a production-level account?

Does Plaid process transactions

Does Plaid support Multi-Factor Authentication (MFA)?

Does Plaid support business bank accounts?

Does Plaid support international bank accounts?

How do I integrate with Plaid?

Where can I learn more about Plaid security?

What are Plaids products?

Plaid offers six products: Auth, Transactions, Identity, Balance, Income and Assets. Each product returns data that can be used to deliver high-quality experiences to end users.

Auth | ACH authentication (account and routing numbers)

Transactions | Contextualized account and transaction data

Identity | Name, phone number, email, and physical address

Balance | Real-time balance checks

Income| Income validation

Assets| Asset validation

All of our products can be accessed through a single integration, enabling you to build customized solutions that suit your business needs. You can find additional detail about all products in our documentation. If you require further information, please reach out through our contact page.

How many banks does Plaid support?

We support each of our products across thousands of financial institutions. A full list of supported institutions is available via the API. Please also feel free to reach out through our contact page for more details.

What type of information does Plaid provide via Transactions?

The Transactions endpoint returns data elements including current and available balance, name of the users bank account, transaction pending status, geo-coordinates of transaction location, transaction categorization, and a statistical confidence score for category and location. If theres something else youd like to see, wed love to hear from you. Share your feedback and get answers to any additional questions you have about our products and your data needs by contacting our team.

How often do you pull transaction data?

Plaid pulls transaction data up to several times times per day. When new data is ready, we can notify you via webhooks.

How much does Plaid cost?

Your first live accounts are free in the development environment, and there is no limit on the number of Sandbox items that you may generate.You can learn more about our production plans on our pricing page. Reach out to us to receive details for all products in production. Looking forward to learning about what youre building!

Can I test Plaids data and products?

Yes! You can create an account on our site to gain immediate access to the platform and a live set of API keys, and youre able to add your first 100 live accounts for free in the development environment.

Once Ive tested Plaid, how do I upgrade to a production-level account?

Please follow these steps, and we'll be in touch shortly.

Does Plaid process transactions?

No, we don't process transactions (which actually sends money between accounts). Instead, our Auth product instantly authenticates accounts for ACHeliminating the need for users to enter account and routing numbers or deal with micro-deposits. Plaid authenticates accounts using online banking credentials, making it possible to begin transferring money immediately. You can read more on our site. We're processor agnostic, so you can use any provider you like, but we've also partnered with Stripe to tokenize the whole process.

Does Plaid support Multi-Factor Authentication (MFA)?

Our API supports MFA processes at all supported institutions.

Does Plaid support business bank accounts?

Yes, Plaid supports both consumer and business bank accounts.

Does Plaid support international bank accounts?

Plaid supports both U.S. and Canadian institutions today. If you are interested in other countries and regions, please reach out through our contact page for more details on our roadmap.

How do I integrate with Plaid?

Plaid Link is the quick and secure way to integrate with the Plaid API. Link is a drop-in module that handles credential validation, multi-factor authentication, and error handling for each institution that we support all while keeping credentials from ever hitting your server. Head over to the Link documentation to get started.

Where can I learn more about Plaid security?

We take security seriously. You can learn more about our security practices on our security page, but in short, we tokenize and encrypt sensitive data and advocate for the broader use of these protocols throughout the industry. We have passed a SOC 2 audit and regularly undergo compliance and pen testing.

Finally, how do you pronounce Plaid?

Our name rhymes with glad! If you have additional questions, please reach out to our team from this contact page and we'll respond shortly.

stripe_bank_account_tokennotreturned

stripe_bank_account_token nil

Stripe::InvalidRequestError: No such token

stripe_bank_account_tokennotreturned

Ensure your accounts are linked

When astripe_bank_account_tokenis not returned, a typical cause is that yourStripe and Plaid accounts havenot yet beenlinked. First, be sure thatyour Stripe account has been configuredto accept ACH transfers.Then, linkyour Stripe account to your Plaid account. Now that your accounts are linked, make the request again. If a stripe_bank_account_token is still not returned, see below.

Ensure users are selecting an account in Plaid Link

A stripe_bank_account_token will only bereturned if Select Account has been enabled within Link.With Select Account enabled, theaccount_idfor the account that the user chose will be passed in the second parameter of the onSuccess callback. After you've received thepublic_tokenandaccount_id,send themto your app server, and make an /item/public_token/exchangeAPI request. Plaid will returna Plaid APIaccess_token. Send the access_token and the account_id to /processor/stripe/bank_account_token/create, and in response, you will receive a Stripe bank account token:

{

"stripe_bank_account_token": "btok_5oEetfLzPklE1fwJZ7SG",

"request_id": "[Unique request ID]"

}

Use thestripe_bank_account_tokento initialize ACH payments via Stripe and theaccess_tokento send requests to any of Plaid's otherendpoints.

stripe_bank_account_token nil Stripe::InvalidRequestError: No such token

This error is returned by Stripe's API when a test mode bank_account_token is used in a live Stripe API call.

To generate test mode bank accounts tokens that are associated with one of Stripe's test bank accounts (the test US/CA bank account with account number000123456789 and routing number 110000000), initialize Linkwithyour ownpublic_key(rather thantest_key) and use Plaid Sandbox credentials to authenticate with a financial institution. Send thepublic_tokenandaccount_id, received from Link's onSuccess callback, to your app server. Then make a request to /item/public_token/exchange with the public_token and your client_idand secret (available from your Plaid Dashboard ). The /item/public_token/exchange endpoint will return an access_token. Send the access_token and the account_id to /processor/stripe/bank_account_token/create. In response, you will receive a Stripe test mode bank account token:

{

"stripe_bank_account_token": "btok_5oEetfLzPklE1fwJZ7SG",

"request_id": "[Unique request ID]"

}

Regardless of which Plaid Sandbox account_id is provided in the/processor/stripe/bank_account_token/createrequest, the test mode stripe_bank_account_token that is generated will always be associated with the Stripe test account and routing number. The test mode stripe_bank_account_tokenwill be associated with the Stripe account that you linked via the Plaid Dashboard. Once you're successfully retrieving Stripebank_account_tokens, you'llbe ready tomake the ACH transaction with Stripe! Head to Stripe'sACH guide to get started, and if you have any issues, please reach out to Stripe Support.

Every Plaid API request returns an accounts key with information about the account(s) affiliated with a users credentials:

{

"accounts": [{

"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",

"balances": {

"available": 100,

"current": 110,

"limit": null

},

"mask": "0000",

"name": "Plaid Checking",

"official_name": "Plaid Gold Checking",

"subtype": "checking",

"type": "depository"

}],

"numbers": [{

"account": "9900009606",

"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",

"routing": "011401533",

"wire_routing": "021000021"

}],

"item": {Object},

"request_id": "45QSn"

}

Each accounts _id property is unique. An account's _id will not change, except when Plaid is unable to match the account as it is stored in our system with the data returned by the financial institution. This may occur, for example, when the name of the account changes substantially. In cases like this, a new account _id will be assigned to the account. Additionally, if an access_token is deleted, and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date, the new account _id will be different from the account _id affiliated with the original access_token. Plaids system automatically detects when accounts are opened or closed. If an account is closed, the account and any transactions associated with that account will no longer be returned in API responses.

How to track users across items

Do items or access tokens expire?

How do I remove an item?

What are the differences among apublic_token,access_token, and anitem?

How are tokens formatted?

How to track users across items

A new, unique item is generatedevery time you create an item. If one set of credentials were used to create an item twice, you would receive two unique items. You can check whether credentials have been previously used to create an item by comparing the items accounts.name and accounts.mask.

Do items or access tokens expire?

Items do not expire. access_tokens, which are used to make API requests on behalf of an item, do not expire unless they are rotated.

How do I remove an item?

To deactivate an item, send a POST request to /item/remove, as here:

curl -X POST https://sandbox.plaid.com/item/remove \

-H 'content-type: application/json' \

-d '{

"client_id": String,

"secret": String,

"access_token": String

}'

We do not currentlyoffer a method for the end user to directly remove an item,but you could add this feature to your integration by providing amethod for your users totriggera request to /item/remove.

What are the differences among a public_token, access_token, and an item?

An item represents a set of credentials at a financial institution. It is unique and does not expire. Access its data by making requests with an access_token.Retrieve an access_token by exchanging a public_token.

A public_token is a short-lived token returned by Plaid Link when creating an item. It can be exchanged for an access_token or used to initialize Link in update mode on behalf of an item.

An access_token is a rotatable token affiliated with an item. It is used to make product requests on behalf of an item.

How are tokens formatted?

Tokens follow this format: [type]-[env]-[uuid] Possible types: public, access, processor Possible environments: sandbox, development, production For example: access-development-7c69d345-hda9-ka68-ahs3-e9317406a2

Webhook behavior in Plaids Sandbox and Development environments will mimic behavior in Plaids Production environment. That is, creating an Item in either environment will trigger INITIAL_UPDATE and HISTORICAL_UPDATE webhooks; updating an Itemwebhook will trigger a WEBHOOK_UPDATE_ACKNOWLEDGED webhook; if a Development environments Item has a transaction that is removed, a TRANSACTIONS_REMOVED webhook will be triggered; and if an Item is in an error state, an ERROR webhook will be triggered.

Each transaction has a date property, whose value is derived from information provided by the financial institution. Thedate is in ISO 8601 format, YYYY-MM-DD, and it does not contain timezone information. A posted transactions dateshould reflect the date the transaction was posted, which may differ from the date on which the transaction actually occurred. See the Pending transaction overview for more information.

The Transactions product returns transactions associated with an item.To obtain transaction information,querythe /transactions/get endpoint. When new transactions are available for an item, Plaid will send a DEFAULT_UPDATE webhook. As such, make transactionsrequests in response to these webhooks rather than on timed intervals.

The Plaid Link + Stripe ACH integration is compatiblewith Plaid's API Sandbox and Stripe's test mode API.

To generate test mode bank account tokens associated with one of Stripe's test bank accounts the test US/CA bank account with account number000123456789 and routing number 110000000initialize Plaid Linkwithyour ownpublic_key(nottest_key), and use Plaid's Sandbox credentials when authenticating. Send thepublic_tokenandaccount_id, received from Plaid Link's onSuccess callback, to your app server. Then make a request to /item/public_token/exchange with the public_token and your client_idand secret (available from your Plaid Dashboard ). The /item/public_token/exchange endpoint will return an access_token. Send the access_token and the account_id to /processor/stripe/bank_account_token/create. In response, you will receive a Stripe test mode bank account token:

{

"stripe_bank_account_token": "btok_5oEetfLzPklE1fwJZ7SG",

"request_id": "ab1227Efsd1dd4A"

}

Regardless of which Plaid Sandbox account_id is provided in the/processor/stripe/bank_account_token/createrequest, the test mode stripe_bank_account_token that is generated will always be associated with the Stripe test account and routing number. The test mode stripe_bank_account_token will be associated with the Stripe account that you linked in the PlaidDashboard. Once you're successfully retrieving Stripebank_account_tokens, you'reready tomakeACH transactions with Stripe. Head to Stripe'sACH guide to get started, and if you have any issues, please reach out to Stripe Support.

You can easily customize Plaid Link to create the best look and feel for your application. All customizations are done directly from your Plaid Dashboard, and you can preview changes in real time before publishing changes.

Background ColorYou can adjust the background color (as well as the opacity) behind the Plaid Link module to match your application's branding.

ConsentThe first pane your user will see when they enter Plaid Link is the Consent pane. You can customize the copy of the Consent pane title and select from a few button text options.

Institution SelectIn the institution select pane, you can customize the title and select which institutions are pre-populated on this pane. This is especially useful if you know specific institutions are more popular among your user base.

Institution SearchYou can customize the copy that shows up when your user chooses to search for their institution within the search bar. You can also customize the copy within the pane and on the Exit button if a user's search returned no results.

ConnectedYour user will see this pane once they have successfully connected their institution to Plaid. You can customize the title, the main text, and the button text of this pane.

ReconnectedYour user will land on this pane when they have successfully reconnected their institution to Plaid via Plaid Link in Update mode. Similarly to the Connected pane, you can customize the title, main text, and button text of this pane.

Select AccountThis setting allows you to toggle on or off an additional pane where your user can view the individual accounts associated with their institution and can specify which account(s) they want to connect. If you enable account selection, you can also adjust whether your user select one account or multiple accounts during this pane. Plaid will return which account(s) your user selects via the onSuccess callback.

Plaid provides one secret for each of our three environments; Sandbox, Development, and Production. Both Production and Development secrets are provided once you request and receive access. In the case that a secret has been compromised, you are able to rotate any of your secrets in the Keys section of your Dashboard.

Steps to rotate a secret

Start the rotation: Click on the Rotate secret icon that is on the right-most side of the secret field. A new secret will be created and both the new and old secrets will remain active until you delete one of them

Integrate with your new secret: Copy your new secret and swap it out in your integration

Delete the old secret: Once you have tested the new secret, you can now delete your old secret by clicking the Delete icon that is on the right-most side of the secret field

Note: You are also able to delete the new secret if you want to cancel the rotation.

Secret permissions

Permissions for each secret are also on a per-environment basis. You are able to edit them for each teammate by visiting the Team section of your Dashboard and clicking the Edit button next to a teammate. Teammates without any secrets access will not be able to view the public_key and client_id.

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for financial institutions supported by Plaid. This article highlights some best practices and considerations to ensure a successful Plaid Link integration.

Initialize Link with the correct product(s)

Within your Plaid Link initialization code, you can specify one or more products. All products except for our Balance product can be used to initialize Plaid Link. Which product(s) you specify here will determine which institutions are displayed within Plaid Link. For example, if you initialize Plaid Link with Auth only, only institutions that we have Auth coverage for today will be searchable within Plaid Link. If you specify multiple products, only institutions that we have coverage for all products specified will be searchable.

Please note that initializing Plaid Link with a specific product array will trigger a billing event for each product.

Specify a webhook URL

Within your Plaid Link initialization code, you can also specify a webhook URL. This webhook URL will be assigned to each Item that is created through this Plaid Link instance. More information on webhooks can be found here.

Plaid Link callbacks

Plaid Link has three types of callbacks: onSuccess, onExit, and onEvent. The onSuccess callback is called when your user successfully links their account. This callback also includes the public_token.

The onExit callback is called when your user exits Plaid Link without linking their account. This callback will include metadata that gives details on where your user exited the Plaid Link flow. Depending on the point of exit, you can direct users to subsequent or alternative flows automatically. For example, in the case where the onExit callback contains a metadata status of INSTITUTION_NOT_FOUND, you might consider automatically navigating your user to a backup flow.

The onEvent callback is called during each transition within Link and gives you insight into your user's journey within Plaid Link. This information can help you track conversion within Plaid Link. More information on conversion tracking can be found here.

To add or update a webhook for a pre-existing Item, submit a POST request to /item/webhook/update with the new or updated webhook:

curl -X POST https://sandbox.plaid.com/item/webhook/update \

-H 'content-type: application/json' \

-d '{

"client_id": String,

"secret": String,

"access_token": String,

"webhook": "https://plaid.com/updated/hook"

}'

Plaid sends a WEBHOOK_UPDATE_ACKNOWLEDGED webhook when you successfully update an Items webhook.

ExampleWEBHOOK_UPDATE_ACKNOWLEDGED webhook:

{

"webhook_type": "ITEM",

"webhook_code": "WEBHOOK_UPDATE_ACKNOWLEDGED",

"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",

"error": null,

"new_webhook": https://plaid.com/example/webhook"

}

The Plaid + Dwolla integration can be leveraged for institutions that support Plaids Auth product.

Use the /institutions/get endpoint to retrieve financial institutions that support Auth's credential-based login, or the /institutions/search endpoint to retrieve the list of products that are supported for a given institution. Specifically, the products field will show the list of available products. If auth is available, then the institution is compatible with the Dwolla integration.

Example /institutions/search response:

{

"institutions": [

{

"credentials": [

{

"label": "User ID",

"name": "username",

"type": "text"

},

{

"label": "Password",

"name": "password",

"type": "password"

}

],

"has_mfa": true,

"institution_id": "ins_109509",

"mfa": [

"code",

"list",

"questions",

"selections"

],

"name": "First Gingham Credit Union",

"products": [

"balance",

"credit_details",

"auth",

"info",

"numbers",

"transactions"

]

},

...

],

"request_id": "DLVvK"

}

The Plaid + Dwolla integration combines Dwolla's ACH processor with Plaid's Auth product.

When a Plaid public_token is created, you'll incur a one-time fee from Plaid. See our Pricing page for more pricing information, and refer to your Order Form for specific billing terms.

To learn more about Dwollas pricing, please contact Dwollas sales team or your dedicated Plaid account manager and refer to your Services Agreement for specific billing terms.

While testing the Plaid + Dwolla integration you will want ensure that both APIs are configured to make requests to the Plaid API Sandbox and Dwollas Sandbox environments. The Dwolla Sandbox and Production environments are not compatible with the Plaid Development environment.

Note: This assumes you have already created a Customer within the Dwolla API.

Generate a Plaid public_token after a user has authenticated and created an Item. This public_token, along with the account_id, must be exchanged for a Plaid access_token by your back-end server making a call to the Plaid API. Finally, youll send the access_token and account_id to the Plaid API in exchange for a Dwolla processor_token which will be sent to the Dwolla API.

Using this processor_token, youll pass this in as the value of the plaidToken request parameter, along with a funding source name in the request to create a funding source for a Customer:

POST https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C/funding-sourcesContent-Type: application/vnd.dwolla.v1.hal+jsonAccept: application/vnd.dwolla.v1.hal+jsonAuthorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY{ "plaidToken": "processor-sandbox-161c86dd-d470-47e9-a741-d381c2b2cb6f", "name": "Jane Does Checking"}...HTTP/1.1 201 CreatedLocation: https://api-sandbox.dwolla.com/funding-sources/375c6781-2a17-476c-84f7-db7d2f6ffb31

Onceyou'vereceived a successful response from the Dwolla API, youll use the unique funding source URL to identify the Customers bank when initiating ACH transfers. If you have any issues during the testing process, please reach out to Dwolla developer support.

Eachtransaction_id is a case-sensitive value that identifies a specific transaction. Every Transactions API response includes atransactionsobject with information about available transactions affiliated with an Item:

"transactions": [

{

"account_id": "vokyE5Rn6vHKqDLRXEn5fne7LwbKPLIXGK98d",

"amount": -500,

"category": null,

"category_id": null,

"date": "2017-01-29",

"location": {Object},

"name": "United Airlines",

"payment_meta": {Object},

"pending": false,

"pending_transaction_id": null,

"transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",

"transaction_type": "special"

},

{

"account_id": "XA96y1wW3xS7wKyEdbRzFkpZov6x1ohxMXwep",

"amount": 78.5,

"category": [

"Food and Drink",

"Restaurants"

],

"category_id": "13005000",

"date": "2017-01-29",

"location": {

"address": "262 W 15th St",

"city": "New York",

"state": "NY",

"zip": "10011",

"coordinates": {

"lat": 40.740352,

"lon": -74.001761

}

},

"name": "Golden Crepes",

"payment_meta": {Object},

"pending": false,

"pending_transaction_id": null,

"transaction_id": "4WPD9vV5A1cogJwyQ5kVFB3vPEmpXPS3qvjXQ",

"transaction_type": "place"

}

]

If more than oneItemhas been created for one set of credentials, adifferent transaction_ididentifying the same underlying transaction will be returned for each Item. If a transaction is removed, thetransaction_id will not be returned in subsequent Transactions requests.