Plaid logo
Docs
ALL DOCS

Transfer

  • Transfer Overview
  • Transfer Application
  • Creating transfers
  • Monitoring transfers
  • Plaid Ledger flow of funds
  • Transfer Dashboard
  • Refunds
  • Recurring transfers
  • Transfer UI
  • Platform Payments
  • Errors and troubleshooting
  • Testing in Sandbox
  • Legacy Flow of funds
Plaid logo
Docs
Close search modal
Ask Bill!
Ask Bill!
Hi! I'm Bill! You can ask me all about the Plaid API. Try asking questions like:
  • How do I fix an Item in ITEM_LOGIN_REQUIRED state?
  • How do I set up Link on the web?
  • How do I set up a webhook for IDV?
Note: Bill isn't perfect. He's just a robot platypus that reads our docs for fun. You should treat his answers with the same healthy skepticism you might treat any other answer on the internet. This chat may be logged for quality and training purposes. Please don't send Bill any PII -- he's scared of intimacy. All chats with Bill are subject to Plaid's Privacy Policy.
Plaid.com
Log in
Get API Keys
Open nav

Transfer Sandbox

Use Sandbox to test your transfer integration

While all newly created teams can use Transfer in Sandbox by default, some older teams may need to be manually enabled. If you receive an error indicating that the product is not enabled for your account when attempting to use Transfer in the Sandbox environment, contact Support or your Plaid Account Manager to request access.

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

Simulating money movement, events, and webhooks

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.

Using the Plaid Dashboard UI to simulate sandbox events.
You can simulate many Sandbox events using the Plaid Dashboard.

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.

Action to simulateSimulation endpoint
Transfer events/sandbox/transfer/simulate
Refund events/sandbox/transfer/refund/simulate
Ledger withdrawals sweep events/sandbox/transfer/ledger/withdraw/simulate
Ledger deposits sweep events/sandbox/transfer/ledger/deposit/simulate
Ledger pending-to-available funds movements/sandbox/transfer/ledger/simulate_available
Webhooks/sandbox/transfer/fire_webhook

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.

Automatic Sandbox simulations

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.

In Production, transfer state changes can take minutes to hours depending on processing time. Sandbox simulations provide immediate state transitions for testing purposes.

Transfer state transitions

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

AmountState Transition Path
$11.11pending → posted → settled → funds available (ACH debits only)
$22.22pending → failed
$33.33pending → posted → settled → funds available (ACH debits only) → returned (R01)
$44.44pending → posted → settled → funds available (ACH debits only) → returned (R02)
$55.55pending → posted → settled → funds available (ACH debits only) → returned (R16)
$66.66pending → posted → settled → returned
Refund state transitions

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

AmountState Transition Path
$1.11pending → posted → settled
$2.22pending → failed
$3.33pending → posted → settled → returned
Sweep State Transitions

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

AmountState Transition Path
$111.11pending → posted → settled → funds available (deposits only)
$222.22pending → failed
$333.33pending → posted → settled → funds available (deposits only) → returned
$444.44pending → posted → settled → returned

Testing Plaid Ledger flow of funds

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

Wire transfers

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.

Issuing payouts with a Plaid Ledger
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.
Receiving payments via Plaid Ledger
  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.

Simulating a return with Plaid Ledger
  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.

Setting balances

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.

Simulating recurring transfers

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.

Sample Sandbox recurring transfer scenarios
  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".

Testing Platform Payments end-user onboarding

The following test scenarios are specific to Platform customers only.

In Sandbox, Reseller partners must use /transfer/originator/create instead of the /partner/customer/create and /partner/customer/enable endpoints that they would use in Production.

Simulating onboarding end-customers

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.

Was this helpful?
Developer community
GitHub
GitHub
Stack Overflow
Stack Overflow
YouTube
YouTube
Discord
Discord