Sandbox 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.

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.

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.

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. Items.js illustrates how to incorporate the handling and testing of update mode using the /sandbox/item/reset_login endpoint.

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.

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.

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.

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 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.

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.