This chapter describes step by step how you can implement virtual cash management with the Investment API. We show you the necessary API calls with sample code for a virtual cash increase or decrease.
If you want to learn more about the concept, go to 'Introduction', and in the chapter 'Use Cases' you can find out more about some example processes related to virtual cash.
Authentication scopes —
virtual_cash_balances:adminFor more information, refer to Authentication scopes.
Before implementing virtual cash management, ensure you have:
Webhook handler ready — Set up a webhook endpoint to listen for virtual cash lifecycle events.
- Subscribe to
VIRTUAL_CASH_INCREASE.*andVIRTUAL_CASH_DECREASE.*events.
For more information, refer to Implementing webhooks.
- Subscribe to
The settlement of trades must be executed via Upvest's post-trade settlement and treasury procedure. In this process, payments do not have to be made for the deposits, but only for the corresponding orders.
To submit a virtual cash increase, make the following request:
POST virtual_cash_balances/increases
Example request
{
"account_group_id": "2596db3b-0d03-4651-9eda-970910479dfb",
"amount": "200.00",
"currency": "EUR"
}| Parameter | Description |
|---|---|
account_group_id | Required. ID of the account group for which the balance increase is to be applied. |
amount | Required. The amount by which to increase. |
currency | Required. The currency in which the increase is to be made. Currently supports EUR or GBP. |
Example response
{
"id": "6ffa6b16-2380-4e7a-88b2-ae625c8eef99",
"created_at": "2020-08-24T14:15:22Z",
"updated_at": "2020-08-24T14:15:22Z",
"account_group_id": "ac1c39e9-2101-46b8-a624-d10a9e351b6c",
"amount": "200.00",
"currency": "EUR",
"status": "ISSUED"
}For certain tax wrappers, like the German pension plans, Upvest may cancel a virtual cash increase if the increase would cause the end user to exceed their allowance limit.
This allows us to automatically prevent the end user from over-contributing to their pension plan.
When this occurs, Upvest sends a VIRTUAL_CASH_INCREASE.CANCELLED webhook event to inform the client of the cancellation.
For the increase, you receive the following event:
- The request for the increase was created.
- The increase request was confirmed or cancelled.
| Event | Description |
|---|---|
VIRTUAL_CASH_INCREASE.ISSUED | The request for the increase was created. |
VIRTUAL_CASH_INCREASE.CONFIRMED | The increase request was confirmed so that the balance is now available for trading. |
VIRTUAL_CASH_INCREASE.CANCELLED | The increase request was cancelled due to exceeding the end user's tax wrapper allowance. |
Recommended: Use webhooks to track virtual cash operations
Set up a webhook listener for VIRTUAL_CASH_INCREASE.* events to track the increase lifecycle from ISSUED through CONFIRMED. You will receive automatic notifications when each operation completes rather than needing to poll for status updates.
For more information, refer to Virtual cash webhook events
In some cases, if the increase you made was more than was needed for the order, it is best to reduce the remaining balance. This way we can keep the balance free of rounding dust and misleading cash balances.
To submit a virtual cash decrease, make the following request:
POST virtual_cash_balances/decreases
Example request
{
"account_group_id": "2596db3b-0d03-4651-9eda-970910479dfb",
"amount": "200.00",
"currency": "EUR"
}| Parameter | Description |
|---|---|
account_group_id | Required. ID of the account group for which the balance increase is to be applied. |
amount | Required. The amount by which to increase. |
currency | Required. The currency in which the increase is to be made. Currently supports EUR or GBP. |
Example response
{
"id": "6ffa6b16-2380-4e7a-88b2-ae625c8eef99",
"created_at": "2020-08-24T14:15:22Z",
"updated_at": "2020-08-24T14:15:22Z",
"account_group_id": "ac1c39e9-2101-46b8-a624-d10a9e351b6c",
"amount": "200.00",
"currency": "EUR",
"status": "ISSUED"
}For the increase you will receive the following event:
- The request for the decrease was created.
- The decrease request was confirmed.
- The decrease went into the backlog.
| Event | Description |
|---|---|
VIRTUAL_CASH_DECREASE.ISSUED | The request for the decrease was created. |
VIRTUAL_CASH_DECREASE.CONFIRMED | The decrease request was confirmed; the cash balance has left the specified account. |
VIRTUAL_CASH_DECREASE.QUEUED | The decrease went into the backlog due to lack of funds. It will be moved to Confirmed status once funds arrive. |
Recommended: Use webhooks to track virtual cash operations
Set up a webhook listener for VIRTUAL_CASH_DECREASE.* events to track the decrease lifecycle from ISSUED through CONFIRMED or QUEUED. You will receive automatic notifications at each state transition, including when a queued operation moves to confirmed after funds arrive, rather than needing to poll for status updates.
For more information, refer to Virtual cash webhook events
It is possible to cancel a virtual cash decrease.
It is only possible to cancel a virtual cash decrease if it has the ISSUED or QUEUED status.
To cancel a virtual cash decrease, make the following request:
DELETE /virtual_cash_balances/decreases/{virtual_cash_decrease_id}
| Path parameter | Description |
|---|---|
virtual_cash_decrease_id | Required. Specify the ID of the decrease that you want to delete. |
For the increase you will receive the following event:
- The specified virtual cash decrease was cancelled.
| Event | Description |
|---|---|
VIRTUAL_CASH_DECREASE.CANCELLED | The specified virtual cash decrease was cancelled. |