Sandbox endpoints

Use the /sandbox/public_token/create endpoint to create a valid public_token for an arbitrary institution ID, initial products, and test credentials. The created public_token maps to a new Sandbox Item. You can then call /item/public_token/exchange to exchange the public_token for an access_token and perform all API actions. /sandbox/public_token/create can also be used with the user_custom test username to generate a test account with custom data. /sandbox/public_token/create cannot be used with OAuth institutions.

1const publicTokenRequest: SandboxPublicTokenCreateRequest = {
2  institution_id: institutionID,
3  initial_products: initialProducts,
4};
5try {
6  const publicTokenResponse = await client.sandboxPublicTokenCreate(
7    publicTokenRequest,
8  );
9  const publicToken = publicTokenResponse.data.public_token;
10  // The generated public_token can now be exchanged
11  // for an access_token
12  const exchangeRequest: ItemPublicTokenExchangeRequest = {
13    public_token: publicToken,
14  };
15  const exchangeTokenResponse = await client.itemPublicTokenExchange(
16    exchangeRequest,
17  );
18  const accessToken = exchangeTokenResponse.data.access_token;
19} catch (error) {
20  // handle error
21}

Use the /sandbox/processor_token/create endpoint to create a valid processor_token for an arbitrary institution ID and test credentials. The created processor_token corresponds to a new Sandbox Item. You can then use this processor_token with the /processor/ API endpoints in Sandbox. You can also use /sandbox/processor_token/create with the user_custom test username to generate a test account with custom data.

1const request: SandboxProcessorTokenCreateRequest = {
2  institution_id: institutionID,
3};
4try {
5  const response = await plaidClient.sandboxProcessorTokenCreate(request);
6  const processorToken = response.data.processor_token;
7} catch (error) {
8  // handle error
9}

/sandbox/item/reset_login/ forces an Item into an ITEM_LOGIN_REQUIRED state in order to simulate an Item whose login is no longer valid. This makes it easy to test Link's update mode flow in the Sandbox environment. After calling /sandbox/item/reset_login, You can then use Plaid Link update mode to restore the Item to a good state. An ITEM_LOGIN_REQUIRED webhook will also be fired after a call to this endpoint, if one is associated with the Item.
In the Sandbox, Items will transition to an ITEM_LOGIN_REQUIRED error state automatically after 30 days, even if this endpoint is not called.

1const request: SandboxItemResetLoginRequest = {
2  access_token: accessToken,
3};
4try {
5  const response = await plaidClient.sandboxItemResetLogin(request);
6  // create a public_token for the Item and use it to
7  // initialize Link in update mode.
8  const pt_request: itemPublicTokenCreateRequest = {
9    access_token: accessToken,
10  };
11  const pt_response = await plaidClient.itemCreatePublicToken(pt_request);
12  const publicToken = pt_response.public_token;
13} catch (error) {
14  // handle error
15}

The /sandbox/item/fire_webhook endpoint is used to test that code correctly handles webhooks. This endpoint can trigger the following webhooks:
DEFAULT_UPDATE: Transactions update webhook to be fired for a given Sandbox Item. If the Item does not support Transactions, a SANDBOX_PRODUCT_NOT_ENABLED error will result.
NEW_ACCOUNTS_AVAILABLE: Webhook to be fired for a given Sandbox Item created with Account Select v2.
AUTH_DATA_UPDATE: Webhook to be fired for a given Sandbox Item created with Auth as an enabled product.
LOGIN_REPAIRED: Fired when an Item recovers from the ITEM_LOGIN_REQUIRED without the user going through update mode in your app.
RECURRING_TRANSACTIONS_UPDATE: Recurring Transactions webhook to be fired for a given Sandbox Item. If the Item does not support Recurring Transactions, a SANDBOX_PRODUCT_NOT_ENABLED error will result.
SYNC_UPDATES_AVAILABLE: Transactions webhook to be fired for a given Sandbox Item. If the Item does not support Transactions, a SANDBOX_PRODUCT_NOT_ENABLED error will result.
PRODUCT_READY: Assets webhook to be fired when a given asset report has been successfully generated. If the Item does not support Assets, a SANDBOX_PRODUCT_NOT_ENABLED error will result.
ERROR: Assets webhook to be fired when asset report generation has failed. If the Item does not support Assets, a SANDBOX_PRODUCT_NOT_ENABLED error will result.
Note that this endpoint is provided for developer ease-of-use and is not required for testing webhooks; webhooks will also fire in Sandbox under the same conditions that they would in Production or Development (except for webhooks of type TRANSFER).

1// Fire a DEFAULT_UPDATE webhook for an Item
2const request: SandboxItemFireWebhookRequest = {
3  access_token: accessToken
4  webhook_code: 'DEFAULT_UPDATE'
5};
6try {
7  const response = await plaidClient.sandboxItemFireWebhook(request);
8} catch (error) {
9  // handle error
10}

The /sandbox/item/set_verification_status endpoint can be used to change the verification status of an Item in in the Sandbox in order to simulate the Automated Micro-deposit flow.
Note that not all Plaid developer accounts are enabled for micro-deposit based verification by default. Your account must be enabled for this feature in order to test it in Sandbox. To enable this features or check your status, contact your account manager or submit a product access Support ticket.
For more information on testing Automated Micro-deposits in Sandbox, see Auth full coverage testing.

1const request: SandboxItemSetVerificationStatusRequest = {
2  access_token: accessToken,
3  account_id: accountID,
4  verification_status: 'automatically_verified',
5};
6try {
7  const response = await plaidClient.sandboxItemSetVerificationStatus(request);
8} catch (error) {
9  // handle error
10}

Use the /sandbox/transfer/fire_webhook endpoint to manually trigger a TRANSFER_EVENTS_UPDATE webhook in the Sandbox environment.

1const request: SandboxTransferFireWebhookRequest = {
2  webhook: 'https://www.example.com',
3};
4try {
5  const response = await plaidClient.sandboxTransferFireWebhook(request);
6  // empty response upon success
7} catch (error) {
8  // handle error
9}

Use the /sandbox/transfer/simulate endpoint to simulate a transfer event in the Sandbox environment. Note that while an event will be simulated and will appear when using endpoints such as /transfer/event/sync or /transfer/event/list, no transactions will actually take place and funds will not move between accounts, even within the Sandbox.

1const request: SandboxTransferSimulateRequest = {
2  transfer_id,
3  event_type: 'posted',
4  failure_reason: failureReason,
5};
6try {
7  const response = await plaidClient.sandboxTransferSimulate(request);
8  // empty response upon success
9} catch (error) {
10  // handle error
11}

Use the /sandbox/transfer/sweep/simulate endpoint to create a sweep and associated events in the Sandbox environment. Upon calling this endpoint, all transfers with a sweep status of swept will become swept_settled, all posted or pending transfers with a sweep status of unswept will become swept, and all returned transfers with a sweep status of swept will become return_swept.

1try {
2  const response = await plaidClient.sandboxTransferSweepSimulate({});
3  const sweep = response.data.sweep;
4} catch (error) {
5  // handle error
6}

Use the /sandbox/transfer/ledger/deposit/simulate endpoint to simulate a ledger deposit event in the Sandbox environment.

1const request: SandboxTransferLedgerDepositSimulateRequest = {
2  sweep_id: 'f4ba7a287eae4d228d12331b68a9f35a',
3  event_type: 'sweep.posted'
4};
5try {
6  const response = await plaidClient.sandboxTransferLedgerDepositSimulate(request);
7  // empty response upon success
8} catch (error) {
9  // handle error
10}

Use the /sandbox/transfer/ledger/simulate_available endpoint to simulate converting pending balance to available balance for all originators in the Sandbox environment.

1try {
2  const response = await plaidClient.sandboxTransferLedgerSimulateAvailable({});
3  const available = response.data.balance.available;
4} catch (error) {
5  // handle error
6}

Use the /sandbox/transfer/ledger/withdraw/simulate endpoint to simulate a ledger withdraw event in the Sandbox environment.

1const request: SandboxTransferLedgerWithdrawSimulateRequest = {
2  sweep_id: 'f4ba7a287eae4d228d12331b68a9f35a',
3  event_type: 'sweep.posted'
4};
5try {
6  const response = await plaidClient.sandboxTransferLedgerWithdrawSimulate(request);
7  // empty response upon success
8} catch (error) {
9  // handle error
10}

Use the /sandbox/transfer/test_clock/create endpoint to create a test_clock in the Sandbox environment.
A test clock object represents an independent timeline and has a virtual_time field indicating the current timestamp of the timeline. Test clocks are used for testing recurring transfers in Sandbox.
A test clock can be associated with up to 5 recurring transfers.

1const request: SandboxTransferTestClockCreateRequest = {
2  virtual_time: '2006-01-02T15:04:05Z'
3};
4try {
5  const response = await plaidClient.sandboxTransferTestClockCreate(request);
6  const test_clock = response.data.test_clock;
7} catch (error) {
8  // handle error
9}

Use the /sandbox/transfer/test_clock/advance endpoint to advance a test_clock in the Sandbox environment.
A test clock object represents an independent timeline and has a virtual_time field indicating the current timestamp of the timeline. A test clock can be advanced by incrementing virtual_time, but may never go back to a lower virtual_time.
If a test clock is advanced, we will simulate the changes that ought to occur during the time that elapsed.
For example, a client creates a weekly recurring transfer with a test clock set at t. When the client advances the test clock by setting virtual_time = t + 15 days, 2 new originations should be created, along with the webhook events.
The advancement of the test clock from its current virtual_time should be limited such that there are no more than 20 originations resulting from the advance operation on each recurring_transfer associated with the test_clock.
For example, if the recurring transfer associated with this test clock originates once every 4 weeks, you can advance the virtual_time up to 80 weeks on each API call.

1const request: SandboxTransferTestClockAdvanceRequest = {
2  test_clock_id: 'b33a6eda-5e97-5d64-244a-a9274110151c',
3  new_virtual_time: '2006-01-02T15:04:05Z'
4};
5try {
6  const response = await plaidClient.sandboxTransferTestClockAdvance(request);
7} catch (error) {
8  // handle error
9}

Use the /sandbox/transfer/test_clock/get endpoint to get a test_clock in the Sandbox environment.

1const request: SandboxTransferTestClockGetRequest = {
2  test_clock_id: 'b33a6eda-5e97-5d64-244a-a9274110151c'
3};
4try {
5  const response = await plaidClient.sandboxTransferTestClockGet(request);
6  const test_clock = response.data.test_clock;
7} catch (error) {
8  // handle error
9}

Use the /sandbox/transfer/test_clock/list endpoint to see a list of all your test clocks in the Sandbox environment, by ascending virtual_time. Results are paginated; use the count and offset query parameters to retrieve the desired test clocks.

1const request: SandboxTransferTestClockListRequest = {
2  count: 2
3};
4try {
5  const response = await plaidClient.sandboxTransferTestClockList(request);
6  const test_clocks = response.data.test_clocks;
7} catch (error) {
8  // handle error
9}

Use the /sandbox/income/fire_webhook endpoint to manually trigger a Payroll Income webhook in the Sandbox environment.

1const request: SandboxIncomeFireWebhookRequest = {
2  item_id: 'Rn3637v1adCNj5Dl1LG6idQBzqBLwRcRZLbgM',
3  webhook: 'https://webhook.com/',
4  verification_status: 'VERIFICATION_STATUS_PROCESSING_COMPLETE',
5};
6try {
7  const response = await plaidClient.sandboxIncomeFireWebhook(request);
8  // empty response upon success
9} catch (error) {
10  // handle error
11}