Implementing virtual cash

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.

TIP

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.


Prerequisites

 ✓   Post-trade settlement and treasury
Details

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.


Increasing virtual cash

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"
}
ParameterDescription
account_group_idRequired. ID of the account group for which the balance increase is to be applied.
amountRequired. The amount by which to increase.
currencyRequired. The currency in which the increase is to be made. Currently only EUR is possible.

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"
}

Webhooks

For the increase you will receive the following events:

  • The request for the increase was created.
  • The increase request was confirmed.
EventDescription
VIRTUAL_CASH_INCREASE.ISSUEDThe request for the increase was created.
VIRTUAL_CASH_INCREASE.CONFIRMEDThe increase request was confirmed so that the balance is now available for trading.

Decreasing virtual cash

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"
}
ParameterDescription
account_group_idRequired. ID of the account group for which the balance increase is to be applied.
amountRequired. The amount by which to increase.
currencyRequired. The currency in which the increase is to be made. Currently only EUR is possible.

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"
}

Webhooks

For the increase you will receive the following events:

  • The request for the decrease was created.
  • The decrease request was confirmed.
  • The decrease went into the backlog.
EventDescription
VIRTUAL_CASH_DECREASE.ISSUEDThe request for the decrease was created.
VIRTUAL_CASH_DECREASE.CONFIRMEDThe decrease request was confirmed; the cash balance has left the specified account.
VIRTUAL_CASH_DECREASE.QUEUEDThe decrease went into the backlog due to lack of funds. It will be moved to Confirmed status once funds arrive.

Cancelling a virtual cash decrease

It is possible to cancel a virtual cash decrease.

INFO

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 parameterDescription
virtual_cash_decrease_idRequired. Specify the ID of the decrease that you want to delete.

Webhook

For the increase you will receive the following event:

  • The specified virtual cash decrease was cancelled.
EventDescription
VIRTUAL_CASH_DECREASE.CANCELLEDThe specified virtual cash decrease was cancelled.

Was this page helpful?