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.
USER_PERMISSION_REVOKED: Indicates an end user has revoked the permission that they previously granted to access an Item. May not always fire upon revocation, as some institutions’ consent portals do not trigger this webhook. Upon receiving this webhook, it is recommended to delete any stored data from Plaid associated with the account or Item.
USER_ACCOUNT_REVOKED: Fired when an end user has revoked access to their account on the Data Provider's portal. This webhook is currently sent only for Chase and PNC Items, but may be sent in the future for other financial institutions. Upon receiving this webhook, it is recommended to delete any stored data from Plaid associated with the account or Item.
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}

Use the /sandbox/cra/cashflow_updates/update endpoint to manually trigger an update for cashflow updates (Monitoring) in the Sandbox environment.