Sandbox Overview
Use the Sandbox to quickly develop and test your app
API Reference
View Sandbox-specific requests, responses, and example code
View Sandbox APIQuickstart
Learn about Plaid's key concepts and run starter code
Get startedSandbox overview
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.
Using Sandbox
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 user_good
/ pass_good
.
Most products can be immediately tested in Sandbox with no extra configuration. Some products, such as Payment Initiation (UK and Europe), may require your account be specially enabled. If the product you want to test against is not available in Sandbox, file a request for access ticket via the Dashboard.
Bypassing Link
When doing repeated manual tests, or for writing automated tests against Sandbox, completing the Link flow may be impractical. 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.
ITEM_LOGIN_REQUIRED
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. Items.js illustrates how to incorporate the handling and testing of update mode using the /sandbox/item/reset_login
endpoint.
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.
Remember Me experience
The Link Remember Me experience can be tested in Sandbox with several seeded phone numbers. More details can be found at Testing Remember Me in Sandbox.
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.
Webhooks
Plaid provides a special Sandbox-only endpoint, /sandbox/item/fire_webhook
, that can be used to trigger DEFAULT_UPDATE
, NEW_ACCOUNTS_AVAILABLE
, AUTH_DATA_UPDATE
, RECURRING_TRANSACTIONS_UPDATE
, and SYNC_UPDATES_AVAILABLE
webhooks on demand, allowing you to test that you are receiving webhooks successfully. Webhooks specific to the Income and Transfer products can be sent using the /sandbox/transfer/fire_webhook
and /sandbox/income/fire_webhook
endpoints.
All webhooks that would be fired in Production or Development will also fire in Sandbox, except when using the Transfer product.
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; once your request has been approved, you will be able to add up to 100 live Items in the Development environment.
Some products, such as 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. Also note that some products, such as Identity Verification, Monitor, Transfer, and Virtual Accounts, are not supported in the Development environment.
In order to test US OAuth institutions in Development, you will first need to obtain Production approval. Once you have been approved for Production access, you can test OAuth in the Development environment.