Transfer Sandbox

Sandbox is Plaid's environment for testing using fake data. For more details about getting started with Sandbox environment, including how to skip the Link flow in Sandbox with /item/public_token/create, and testing non-Transfer-specific functionality such as Item errors, see Sandbox.

When creating transfers in Sandbox, see the /transfer/authorization/create documentation on how to generate approved or declined authorization responses.

Any cutoff times applied in Production will also apply in the Sandbox environment. For example, creating a same-day ACH transfer in Sandbox after 3:30 pm ET will automatically update the transfer to standard ACH.

In the Sandbox environment, no real banks are involved and no events are triggered automatically. By default, all transfers, refunds, and sweeps created in Sandbox remain at the pending status until you actively change them. This can be most easily accomplished through the Plaid Dashboard, where you can simulate next steps and common failure scenarios for any transfer that you've created in the Sandbox environment.

If you would like to change the status of a transfer through the API, you can call the following endpoints to simulate events and fire transfer webhooks manually.

When you change the status of a Sandbox transfer, either through the Dashboard or the API, the corresponding webhook will not fire. You must use the /sandbox/transfer/fire_webhook API to send a Transfer webhook in Sandbox.

For a full list of transfer simulations available in Sandbox, see Sandbox endpoints.

For a general overview of the Plaid Sandbox environment, see Sandbox overview.

In addition to manual simulations, the Sandbox environment supports automatic state transitions for transfers, refunds, and sweeps (deposits and withdrawals) when using specific test amounts. These special amounts trigger predefined state transitions without requiring manual intervention through the Dashboard or API.

Once you initiate a transfer with any of these specific amount values, the transfer's stages will be immediately simulated. The appropriate webhooks for Sandbox transfer events will be fired, and you can fetch the events through /transfer/event/sync. You can also view the events' progression on your Transfer Dashboard, on the details page for the specific transfer.

Creating Sandbox transfers with the specified amounts via /transfer/create will result in automatic state transitions.

Creating Sandbox refunds with the specified amounts via /transfer/refund/create will result in automatic state transitions.

Creating Sandbox sweeps with the specified amounts via /transfer/ledger/deposit and /transfer/ledger/withdraw will result in automatic state transitions.

While testing Plaid Ledger in Sandbox, you can always call the following endpoints at any time to verify expected behavior:

• /transfer/get to validate the transfer status change
• /transfer/sweep/get to validate the deposit/withdrawal status change
• /transfer/ledger/get to validate the Ledger balance change

In Sandbox, all customers are enabled for wire transfers in order to facilitate testing. Having access to wire transfers in Sandbox does not mean you are enabled for wires in Production. To request access to wire transfers in Production, contact your Account Manager.

Adding funds to the Plaid Ledger

All new Plaid Ledgers have a starting balance of $100 in Sandbox. Once this is depleted, or if you wish to simulate a larger transfer, you will need to fund the Ledger before testing the payout.

1. Call /transfer/ledger/deposit to create a sweep that adds funds to a Plaid Ledger balance. The funds will immediately show up in the pending balance.
2. Call /sandbox/transfer/ledger/deposit/simulate with sweep.posted as the event_type.
3. Call /sandbox/transfer/ledger/deposit/simulate with sweep.settled as the event_type. This will move your sweep to settled status.
4. Call /sandbox/transfer/ledger/simulate_available in order to simulate the passage of time and transition the funds from pending to available.

Issuing a payout

1. Call /transfer/authorization/create with type=credit and your desired network. To simulate an insufficient funds failure, call /transfer/authorization/create with an amount larger than your current available balance.
2. Call /transfer/create. This will immediately create a transfer and decrement the available balance.

1. Call /transfer/authorization/create with type=debit.
2. Call /transfer/create. This will immediately create a transfer and increment your pending balance in the Plaid Ledger.
3. Call /sandbox/transfer/simulate with posted as the event_type.
4. Call /sandbox/transfer/simulate with settled as the event_type. This will move your transfer to settled status. The funds will remain in pending until the hold is elapsed.
5. Call /sandbox/transfer/ledger/simulate_available to simulate the passage of time and convert the Ledger balance to available. If you are a Platform Payments customer, this will convert all pending balances in all Plaid Ledgers.
6. Call /transfer/ledger/withdraw to create a sweep that withdraws funds from the Plaid Ledger balance. The endpoint will immediately decrement the available balance and create a sweep with pending status.
7. Call /sandbox/transfer/ledger/withdraw/simulate with sweep.posted as the event_type.
8. Call /sandbox/transfer/ledger/withdraw/simulate with sweep.settled as the event_type. This will move your sweep to settled status.

In Production, transfer and sweep status will be updated automatically to reflect the real processing status, and the pending balance will automatically become available after the client-specific hold day.

1. Follow steps 1-3 in Receiving payments via Plaid Ledger section to create a debit and move it to posted.
2. (Optional) To simulate a return after the funds were made available, follow steps 4-5 as well. If you would like to simulate a return before the funds were made available, omit this step.
3. Call /sandbox/transfer/simulate with returned as the event_type. This will move the transfer status to returned and decrement pending balance, which you can verify by calling /transfer/ledger/get.

Testing Instant Payouts

Testing Instants Payouts works the same way as testing ACH Transfers.

To test the /transfer/capabilities/get endpoint in Sandbox, log in using the user_good user Sandbox account (see Sandbox simple test credentials for more information), and use the first 2 checking and savings accounts in the "First Platypus Bank" institution (ending in 0000 or 1111), which will return true. Any other account will return false. If using a custom Sandbox user, set numbers.ach_routing to 322271627 in order to return true.

You can customize the starting balance and certain other data for a linked account by using a Sandbox custom user. The easiest way to set a custom balance is to use a test user in the custom users repo. Using one of the example files, modify the starting balance, then follow the instructions in the repo's README to add the user to your Sandbox.

In the Sandbox environment, recurring transfers can be simulated by using a test_clock object.

A test_clock is a mock clock that has a virtual_time field, indicating the current timestamp on this test clock. You can attach a test_clock to a recurring_transfer in Sandbox by providing a test_clock_id when calling /transfer/recurring/create.

You can advance the virtual_time on a test_clock to a higher value by calling /sandbox/transfer/test_clock/advance, but you can never decrease the virtual_time.

When a test clock is advanced, all active recurring transfers attached to this clock will generate new originations as if the time had elapsed in Production. For instance, assuming a test clock is attached to a weekly recurring transfer, if the test clock is advanced by 14 days, you should see two new transfers being created.

Note that advancing a test clock does not change the status of the transfer objects created by a recurring transfer. Transfers will stay in pending status unless you call /sandbox/transfer/simulate to simulate a transfer status update.

1. Create a test clock using /sandbox/transfer/test_clock/create, with a virtual_time of "2022-11-14T07:00:00-08:00", which is 2022-11-14 7AM PST (Monday).

2. Create a weekly recurring transfer on every Tuesday using /transfer/recurring/create with the test_clock_id returned from step 1. The recurring schedule starts on 2022-11-15, and ends on 2022-11-30.

3. Advance the test clock to "2022-11-15T23:59:00-08:00", which is the end of day 2022-11-15 PST (Tuesday).

4. Since we advanced the test clock to the last minute of Tuesday and the recurring transfer is also scheduled on every Tuesday, we expect to see 1 transfer being created. Inspect the recurring transfer created in step 2 with /transfer/recurring/get. Confirm the transfer_ids field now has 1 element, and the status field is "active".

5. Advance the test clock to "2022-11-29T23:59:00-08:00", which is the end of day 2022-11-29 PST (Tuesday).

6. Inspect the recurring transfer created in step 2 with /transfer/recurring/get. Confirm that the transfer_ids field now has 3 elements, and the status field is now "expired".

7. Advance the test clock to "2022-12-06T23:59:00-08:00", which is the end of day 2022-12-06 PST (Tuesday).

8. Inspect the recurring transfer created in step 2 with /transfer/recurring/get. Confirm that the transfer_ids field still has 3 elements, and the status field remains "expired".

In Sandbox, you can create an end-customer by calling the /transfer/originator/create and then /transfer/questionnaire/create. You will not be able to go through the onboarding UI in Sandbox: the test end-customer will automatically be approved. If you need to test the onboarding UI, you can do so in Production.