Virtual Cash Balances

Trigger a virtual cash decrease

Decreases an account group's virtual cash balance, for example after an order has settled or before a withdrawal.

If the account group does not yet have sufficient real cash, the decrease is queued with status QUEUED and confirmed automatically once funds arrive rather than being rejected. Requires the Idempotency-Key header to prevent duplicate decreases.

See the Virtual cash guide (TOL / BYOL) for supported use cases.

post/virtual_cash_balances/decreases

Request

  • Base URL: https://sandbox.upvest.co
  • URL: https://sandbox.upvest.co/virtual_cash_balances/decreases
  • Auth: OAuth 2 (client credentials, token URL https://sandbox.upvest.co/auth/token, scopes: virtual_cash_balances:admin)

Headers

idempotency-keystring uuid required
Example:ccb07f42-4104-44ad-8e1f-c660bb7b269c

A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed. https://docs.upvest.co/documentation/concepts/api_concepts/idempotency

Request body

account_group_idstring uuid required

Universally Unique Identifier (UUID) of the account group.

amountstring required

A positive cash amount, as a decimal string with up to two decimal places.

currency'EUR' | 'GBP' | 'USD' required

Alphabetic three-letter ISO 4217 currency code.

  • EUR — Euro.
  • GBP — Pound Sterling.
  • USD — The United States dollar.

Response

Virtual Cash Balances Decrease

idstring uuid required

The unique identifier of a virtual cash increase or decrease operation.

created_atstring date-time required

Date and time when the resource was created. RFC 3339-5, ISO8601 UTC

updated_atstring date-time required

Date and time when the resource was last updated. RFC 3339-5, ISO8601 UTC

account_group_idstring uuid required

Universally Unique Identifier (UUID) of the account group.

amountstring required

A positive cash amount, as a decimal string with up to two decimal places.

currency'EUR' | 'GBP' | 'USD' required

Alphabetic three-letter ISO 4217 currency code.

  • EUR — Euro.
  • GBP — Pound Sterling.
  • USD — The United States dollar.
status'ISSUED' | 'CONFIRMED' | 'QUEUED' | 'CANCELLED' required

Status of the virtual cash

  • ISSUED - Virtual cash decrease is created.
  • CONFIRMED - Virtual cash decrease was successfully processed.
  • QUEUED - Virtual cash decrease was queued.
  • CANCELLED - Virtual cash decrease was cancelled.

Changes

No recorded changes to this operation across all 25 revisions of this API.