Plaid logo
Docs
ALL DOCS

Sandbox

  • Overview
  • Sandbox institutions
  • Test credentials
  • Customize test data
Plaid logo
Docs
Plaid.com
Get API keys
Open nav

Sandbox Overview

Use the Sandbox to quickly develop and test your app

API Reference

View Sandbox-specific requests, responses, and example code

View Sandbox API

Quickstart

Learn about Plaid's key concepts and run starter code

Get started

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.

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.

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.

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.

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. Also note that some products, such as Identity Verification, Monitor, and Transfer, are not supported in the Development environment.

Was this helpful?
Developer community
GitHub
GitHub
Stack Overflow
Stack Overflow
YouTube
YouTube
Twitter
Twitter
Discord
Discord