Use the Sandbox to quickly develop and test your app
The Plaid Sandbox is a free and fully-featured environment for application development and testing. All Plaid functionality of both the Plaid API and Plaid Link is supported in the Sandbox environment. A variety of test accounts and institutions are available to test against, and you can create an unlimited number of test Items. Sandbox API keys can be obtained in the Plaid Dashboard.
The Sandbox can be reached by sending HTTPS POST requests to the endpoints on the
sandbox.plaid.com domain. In order to use the Sandbox with a client library, specify Sandbox as your environment when initializing.
The default username/password combination for all Sandbox institutions is
Most products can be immediately tested in Sandbox with no extra configuration. The exception is Payment Initiation (UK and Europe), which requires that your account be specially enabled. To enable your account for Payment Initiation testing on Sandbox, file a request for access ticket via the Dashboard.
Repeatedly completing the Link flow while testing can become tedious, especially if using a complex set of test credentials. As an alternative, you can also create Items in Sandbox via the API, using a special Sandbox-only endpoint,
/sandbox/public_token/create. This endpoint allows you to generate a
public_token for an arbitrary institution ID, initial products, and test credentials.
Simulating data and events
The Sandbox provides rich test data, as well as the ability to generate your own test data. You can also simulate a number of scenarios for testing in Sandbox.
Update mode in Link is used to handle user logins that have become invalid (for example, due to the user changing their password at their financial institution). An Item that needs to be handled via update mode will enter the
ITEM_LOGIN_REQUIRED error state. To test your update mode flow in Sandbox, you can use the
/sandbox/item/reset_login endpoint to force an Item into this state. Sandbox Items will also automatically enter the
ITEM_LOGIN_REQUIRED state 30 days after being created.
An example of using update mode and testing in Sandbox can be found in the Plaid Pattern sample app. This Node app provides code that illustrates how to incorporate the handling and testing of update mode using the
MFA, ReCAPTCHA, and Link errors
Multi-factor authentication, ReCAPTCHA, and a number of Link failure states can all by triggered in the Sandbox by using a custom set of test credentials, using the username
user_good and a specially formatted password depending on the state you would like to trigger. For details, see Test credentials.
Instant Match and micro-deposit-based Auth
While the standard Instant Auth flow does not require special configuration to test, the additional Auth flows such as Instant Match, Same-day Micro-deposits, and Automated micro-deposits require more complex steps such as verifying micro-deposits or routing numbers. The Sandbox environment provides several test institutions and endpoints that can be used to verify these flows. For more details, see Testing Auth flows.
Returning user experience
The Link returning user experience can be tested in Sandbox using the name, phone number, and email address of a specific Sandbox test user. For details, see Testing RUX in Sandbox.
Plaid provides a special Sandbox-only endpoint,
/sandbox/item/fire_webhook, that can be used to trigger
AUTH_DATA_UPDATE webhooks on demand, allowing you to test that you are receiving webhooks successfully.
All webhooks that would be fired in Production or Development will also fire in Sandbox.
Testing with live data using Development
The Plaid Sandbox is one of three Plaid environments, with the other two being Development and Production. In order to test with live data, you can configure your application to use the Development environment. Unlike Sandbox, Development uses real production data and real institutions, and unlike Production, it is free to use. You may add up to a maximum of 100 Items in the Development environment. Keep in mind that Items cannot be moved between environments – Sandbox Items cannot be moved to Development, and Items created in Development cannot be moved to Production.
When you first create your Plaid developer account, it will either have pre-populated access to a very limited number of Items on Development, or no access to Development at all. In either case, you can file a request for Development access via the Dashboard in order to add up to 100 live Items in the Development environment.
Note that some products, such as Liabilities, Investments, Assets, and Identity, require your account to be specially enabled before testing in Development or Production. To enable your account, file a request for access ticket via the Dashboard.