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, or with Plaid's pre-populated Sandbox test accounts.

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}

/sandbox/user/reset_login/ functions the same as /sandbox/item/reset_login, but will modify Items related to a User. This endpoint forces each 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/user/reset_login, You can then use Plaid Link update mode to restore Items associated with the User 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: SandboxUserResetLoginRequest = {
2  user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab',
3  item_ids: ['eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6']
4};
5try {
6  const response = await plaidClient.sandboxUserResetLogin(request);
7} catch (error) {
8  // handle error
9}

The /sandbox/item/fire_webhook endpoint is used to test that code correctly handles webhooks. This endpoint can trigger the following webhooks:
DEFAULT_UPDATE: Webhook to be fired for a given Sandbox Item simulating a default update event for the respective product as specified with the webhook_type in the request body. Valid Sandbox DEFAULT_UPDATE webhook types include: AUTH, IDENTITY, TRANSACTIONS, INVESTMENTS_TRANSACTIONS, LIABILITIES, HOLDINGS. If the Item does not support the product, a SANDBOX_PRODUCT_NOT_ENABLED error will result.
NEW_ACCOUNTS_AVAILABLE: Fired to indicate that a new account is available on the Item and you can launch update mode to request access to it.
SMS_MICRODEPOSITS_VERIFICATION: Fired when a given same day micro-deposit item is verified via SMS verification.
LOGIN_REPAIRED: Fired when an Item recovers from the ITEM_LOGIN_REQUIRED without the user going through update mode in your app.
PENDING_DISCONNECT: Fired when an Item will stop working in the near future (e.g. due to a planned bank migration) and must be sent through update mode to continue working.
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 (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.
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/refund/simulate endpoint to simulate a refund 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: SandboxTransferRefundSimulateRequest = {
2  refund_id: refundId,
3  event_type: 'refund.posted',
4};
5try {
6  const response = await plaidClient.sandboxTransferRefundSimulate(request);
7  // empty response upon success
8} catch (error) {
9  // handle error
10}

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(
7    request,
8  );
9  // empty response upon success
10} catch (error) {
11  // handle error
12}

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(
7    request,
8  );
9  // empty response upon success
10} catch (error) {
11  // handle error
12}

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 or Document 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}