# Cash balance transfers

Upvest provides the Cash balance transfers API to help clients easily move a cash balance between two account groups belonging to the same end user or business, without the cash leaving the system.

This feature helps pre-funding clients easily manage cash balances for end users with more than one account group. Post-trade settlement clients can leverage [virtual cash balance](/products/tol/guides/virtual_cash) increase and decrease for the same effect.

## Before you begin

This guide covers internal cash balance transfers: their functionality and how to implement them. Cash balance transfers are available for users and businesses that hold more than one account group in a single client.

| **Key terms** | **Description** |
|  --- | --- |
| Cash balance | The amount of cash held by an account group in a given currency. Fundings, withdrawals, and all order processes affect it. |
| Account group | The level at which the end-user’s cash balance is held. An end user can hold several account groups, each with its own cash balance. |
| Cash balance transfer | The movement of cash from one account group to another belonging to the same holder. There is no external bank transfer, so no bank settlement period applies. |
| Source account group | The account group the cash is transferred from. |
| Target account group | The account group the cash is transferred to. |
| Settled cash | Cash that is neither locked for trading nor pending settlement. Reported as `available_for_withdrawal` on the cash balance. You can only transfer settled cash that is available for withdrawal. |


## Cash balance transfers at-a-glance

Cash balance transfers offer the following features and functionality:

* **Completely internal:** The cash never leaves the system, so there is no settlement period and no bank fees.
* **Single operation:** The cash leaves the source account group and arrives at the target account group automatically.
* **Near-instant:** The transfer typically completes within seconds.


In addition, the following requirements apply to all cash balance transfers:

* **Same user, same type.** Both account groups must belong to the same user and be of the same [account group type](/products/tol/guides/accounts/accounts_overview#account-group-types).
Note: Only `PERSONAL`, `CHILD`, or `BUSINESS` account group types are supported for cash balance transfers.
* **Settled cash only.** Cash that is pending settlement, locked for trading, or locked for withdrawal, cannot be moved.
* **Three statuses.** Cash balance transfers support three statuses: `ISSUED`, then either `CONFIRMED` or `CANCELLED`. Status changes are automatically provided by the [Cash balance transfers events webhook](/api/cash-balance-transfers/cash_balance_transfer_event).
* **Cancellable before confirmation.** A transfer can be cancelled while it is in the `ISSUED` status. Transfers in the `CONFIRMED` status are considered final and cannot be cancelled.


In rare cases, a balance decrease (e.g. order execution, automatic withdrawal) happens at the same time the transfer is created. If this occurs, we keep the transfer in the `ISSUED` state. Clients can then cancel the balance transfer.

## Our solution for cash balance transfers

| **Functionality** | **Related Endpoint** |
|  --- | --- |
| User and business management | Use the `/users` and `/businesses` endpoints to onboard the holder of both account groups. |
| Account groups | Use the `/account_groups` endpoint to open the account groups the cash moves between. |
| Checking available cash | Use `/account_groups/{account_group_id}/payments/cash_balances` to confirm the source account group holds enough settled cash. |
| Creating a transfer | `POST /payments/cash_balance_transfers` creates the transfer and triggers the cash movement. |
| Retrieving a transfer | `GET /payments/cash_balance_transfers/{cash_balance_transfer_id}` returns a single transfer. |
| Listing transfers | `GET /payments/cash_balance_transfers` returns all transfers.`GET /users/{user_id}/payments/cash_balance_transfers` and`GET /businesses/{business_id}/payments/cash_balance_transfers` return the transfers of one user or business. |
| Cancelling a transfer | `DELETE /payments/cash_balance_transfers/{cash_balance_transfer_id}` cancels a transfer that is still `ISSUED`. |
| Tracking status | Subscribe to `CASH_BALANCE_TRANSFER.*` webhook events to receive each status change. |


Cash balance transfers cover one specific case: cash moving between account groups of the same holder. Other movements use other endpoints as shown below.

Transfers between account groups of different types are not supported. This includes types, like tax wrappers, that must remain physically segregated for regulatory reasons.

| **You want to** | **Use** |
|  --- | --- |
| Move cash between two account groups of the same type for the same user | [Cash balance transfers](/products/tol/guides/payments/cash_balances/cash_balances_transfers)(this guide) |
| Move securities positions rather than cash | [Securities transfers](/products/tol/guides/transfers/securities_transfers_overview) |
| Pay cash out to an external bank account (reference account) | [Withdrawals](/products/tol/guides/payments/cash_balances/cash_withdrawal) |
| Bring cash in from an external bank account | [Top-ups](/products/tol/guides/payments/top_ups/top_ups_intro)[Credit funding](/products/tol/guides/payments/viban/viban_credit_funding_details)[Direct debits](/products/tol/guides/payments/direct_debit/direct_debit_intro) |


### Planning around settled cash

Only settled cash can be transferred. Since settlement occurs in sessions after trade execution, the following applies:

- Sell orders: Cash arising from a sell order becomes available roughly two business days after execution.
- Buy orders: Cash reserved for pending buy orders is not available for transfer.


If your product moves cash immediately after a sale, plan for that delay in your end-user experience rather than retrying the transfer.

Because a balance can change between the moment your end user initiates a transfer and the moment you call the API, check the cash balance immediately before creating the transfer.

The maximum amount that can be transferred is reflected in the `available_for_withdrawal` field.

### Reconciliation and references

To provide a reference value, Upvest includes a unique ID when you create a cash balance transfer. The unique ID appears on every webhook event for that transfer so you can use this value to track the entire lifecycle of the transfer.

You can also store this value for your own records, and use this ID to save the history of the transfer.

### Irreversibility

A `CONFIRMED` transfer cannot be reversed. To undo one, create a new transfer in the opposite direction. If your product allows end users to correct a mistaken transfer, build that as a second transfer rather than a cancellation.