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

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}

/sandbox/payment_profile/reset_login/ forces a Payment Profile into a state where the login is no longer valid. This makes it easy to test update mode for Payment Profile in the Sandbox environment.
After calling /sandbox/payment_profile/reset_login, calls to the /transfer/authorization/create with the Payment Profile will result in a decision_rationale PAYMENT_PROFILE_LOGIN_REQUIRED. You can then use update mode for Payment Profile to restore it into a good state.
In order to invoke this endpoint, you must first create a Payment Profile and go through the Link flow.

1// force a Payment Profile into a login required state
2const request: SandboxPaymentProfileResetLoginRequest = {
3  payment_profile_token: paymentProfileToken,
4};
5try {
6  const response = await plaidClient.sandboxPaymentProfileResetLogin(request);
7} catch (error) {
8  // handle error
9}

Use the /sandbox/transfer/fire_webhook endpoint to manually trigger a Transfer 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 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.

1const request: SandboxTransferSweepSimulateRequest = {
2  client_id,
3  secret,
4};
5try {
6  const response = await plaidClient.sandboxTransferSweepSimulate(request);
7  const sweep = response.data.sweep;
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  client_id,
3  secret,
4  virtual_time: '2006-01-02T15:04:05Z'
5};
6try {
7  const response = await plaidClient.sandboxTransferTestClockCreate(request);
8  const test_clock = response.data.test_clock;
9} catch (error) {
10  // handle error
11}

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 instance, 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 instance, 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: SandboxTransferTestClockCreateRequest = {
2  client_id,
3  secret,
4  test_clock_id: 'b33a6eda-5e97-5d64-244a-a9274110151c',
5  virtual_time: '2006-01-02T15:04:05Z'
6};
7try {
8  const response = await plaidClient.sandboxTransferTestClockAdvance(request);
9} catch (error) {
10  // handle error
11}

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

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

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 an 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}