/v1/simulations/*) let you drive those outcomes yourself, so you can build and test a complete money movement flow end to end before going live.
This walkthrough takes a new integration through the full lifecycle: you open an account (operating or virtual, whichever fits your product), fund it with a simulated incoming deposit, and pay out to a counterparty. You advance each step yourself with the simulation endpoints.
In this guide
Prerequisites
Core walkthrough
Failed and returned payouts
Freeze, drain, and close
What you’ll build
- Open an account (operating or virtual).
- Receive a simulated deposit and watch it settle.
- Save a payout counterparty.
- Send a payout and advance it to
sent.
Prerequisites
-
A sandbox API key with these scopes (or
full_access). See Scopes and inspect your key with GET/v1/api_key.
Steps
Configure your environment
Open an account
ACCOUNT_ID you capture here.- Operating account: one account you hold directly. Simplest option, good for treasury or a single balance.
- Virtual account: a dedicated account per end customer (embedded-banking or FBO model), created under an account program and tied to an account holder.
Operating account
Operating account
active with its own US payment details.ACCOUNT_ID for the steps below:/v1/simulations/accounts in the API Reference →Virtual account
Virtual account
Create an account program
/v1/simulations/account_programs in the API Reference →Create an account holder
country_of_citizenship: use the US individual shape below when it is US, the non-US individual shape for any other country, and the business shape when holder_type is business.beneficiary_data schemas (US individual, non-US individual, business) in the POST /v1/account_holders API Reference →.Create the virtual account
ACCOUNT_ID for the steps below:/v1/accounts in the API Reference →Read the account's payment details
/v1/accounts/{id} in the API Reference →Simulate an incoming deposit
counterparty. The currency must match the account currency. Give it an unstructured_remittance_information value you can recognize later. You use it to find the settled deposit./v1/simulations/deposits in the API Reference →Confirm the deposit settled
settled. Poll the deposits list and match on the remittance information you set./v1/deposits in the API Reference →Save a payout counterparty
aba financial address.id):/v1/counterparties in the API Reference →Create a payout
counterparty_id; the rail is validated against the counterparty’s financial address and selected automatically when omitted.initiated and moves to submitted while it is in flight.id):/v1/payouts in the API Reference →Simulate a successful send
/v1/simulations/payouts/{id}/send in the API Reference →Poll until the payout is sent
Review the account's transactions
credit and the outgoing payout as a debit. Each transaction’s source links back to the deposit or payout that created it (null when it does not map to a retrievable resource). account_id is required. Narrow the results with the optional booked_at.gte and booked_at.lte filters./v1/transactions in the API Reference →Simulate a failed or returned payout
Beyond the happy path, you can drive failure outcomes to test how your integration reacts.Reject a payout before it is sent
Reject a payout before it is sent
submitted (before you simulate a send), simulate the network rejecting it. The payout moves to failed and the funds are released back to your account. Use invalid_routing_number for domestic rails or invalid_account_format for a SWIFT rejection./v1/simulations/payouts/{id}/reject in the API Reference →Return a payout after it is sent
Return a payout after it is sent
sent, simulate the receiving bank returning it. The original payout stays sent; the returned funds arrive as a new standalone deposit (a credit transaction) on your account. Valid reasons are account_closed, invalid_account_format, invalid_routing_number, account_blocked, and unknown./v1/simulations/payouts/{id}/return in the API Reference →The returned funds show up as a new deposit rather than a change to the payout. List your deposits to find it:/v1/deposits in the API Reference →Freeze, drain, and close
Winding down an account or an account program follows the same sequence: freeze it, drain the residual balance to an external destination, settle the drain payout(s), then close it. A frozen account or program can be reactivated with the matchingunfreeze endpoint before you close it.
Close an operating account
Close an operating account
Freeze the account
/v1/simulations/accounts/{id}/freeze in the API Reference →Changed your mind before closing? Reactivate the account with unfreeze:/v1/simulations/accounts/{id}/unfreeze in the API Reference →Drain the residual balance
aba financial address for a USD destination./v1/simulations/accounts/{id}/drain in the API Reference →Settle the drain payout
/v1/simulations/payouts/{id}/send in the API Reference →Close the account
client_request and aml_risk_fraud./v1/simulations/accounts/{id}/close in the API Reference →Close an account program
Close an account program
Freeze the program
/v1/simulations/account_programs/{id}/freeze in the API Reference →Changed your mind before closing? Reactivate the program and its accounts with unfreeze:/v1/simulations/account_programs/{id}/unfreeze in the API Reference →Drain the program
/v1/simulations/account_programs/{id}/drain in the API Reference →Settle each drain payout
/v1/simulations/payouts/{id}/send in the API Reference →