A withdrawal is the process of paying out an end user's or business entity's funds to their reference account.
Withdrawals can be processed for the share of the cash balance with the state AVAILABLE_FOR_WITHDRAWAL. Consider this sell order example demonstrating the process:
Once a sell order is successfully executed, the Investment API calculates the net amount after taxes and fees.
A user’s cash balance is updated by the net amount and assigned the state PENDING_SETTLEMENT.
After the order is settled, funds are transferred to the user's cash account in our system, representing a funding event.
The net amount is now AVAILABLE_FOR_WITHDRAWAL, and therefore can be withdrawn.
The following flow diagram illustrates the withdrawal flow including all related withdrawal status changes, and cash balance updates:
Settlement of funds typically takes two business days.
Before implementing withdrawals, ensure you have:
Webhook handler ready — Set up a webhook endpoint to listen for withdrawal lifecycle events.
- Subscribe to
WITHDRAWAL.*events.
For more information, refer to Implementing webhooks.
- Subscribe to
Withdrawals also require that
an assigned reference bank account exists.
there is sufficient funds in their cash balance (e.g., from a sell order) that are not locked for other purposes such as re-investment.
To request a cash withdrawal, you can specify the cash amount and reference account when triggering a request by
{
"reference_account_id": "295378ec-036e-4f3f-ae5c-2be85c93e837",
"account_group_id": "2596db3b-0d03-4651-9eda-970910479dfb",
"user_id": "e56c14b3-8370-4c04-bc67-7092f7ec113c",
"amount": "200.00",
"currency": "EUR",
"remittance_information": "Withdrawal",
"purpose_code": "OTHR"
}The user_id field is optional and in the process of being removed from the request. You should not include the user_id in the request.
Remittance Information Disclaimer
Please be aware that while our API allows you to specify detailed remittance information for your withdrawals, we cannot guarantee that this information will be transmitted to the recipient's bank without modification.
Some banks may have limitations on the characters or length of remittance information they can process. This may result in the information being truncated, altered, or omitted entirely.
We recommend keeping your remittance information concise and avoiding special characters or non-standard formatting.
Recommended: Use webhooks to track withdrawal status
To track withdrawl status, set up a webhook listener for WITHDRAWAL.PROCESSING and WITHDRAWAL.CONFIRMED events. You will receive automatic notifications as the withdrawal progresses through processing and settlement (typically 1–3 business days).
For more information, refer to Payment webhook events
Webhooks notify you of events in business processes, not the success or failure of the initialisation of those processes.
Please be sure to check the HTTP status of the response to your requests and handle failure cases appropriately.
Once all relevant payment checks have been passed and payment instruction forwarded to payment partner, the withdrawal transitions into status PROCESSING and you will receive a withdrawal event via webhook.
Afterwards, the withdrawal gets executed and confirmed at our payment partner and you will receive a withdrawal CONFIRMED webhook.
In rare instances, a withdrawal may transition to CANCELLED state after CONFIRMED. This normally occurs due to factors outside Upvest's control, such as the receiving bank being unable to identify the account. Depending on the bank's processes, the cancellation event may occurs several days after the initial confirmed event.
When a bank returns a withdrawal, we automatically add the amount to the end user's cash balance.
Based on the withdrawal status, you will also receive a cash balance updated event via webhook. Depending on these statuses, the fields inside the cash balance update can be interpreted as follows:
| Field | Description |
|---|---|
balance | Total cash amount held by the account group |
available_for_withdrawal | Maximum cash amount that can be withdrawn |
Assuming that the user has a settled sell order with EUR 200,00 (following fees and taxes), intended for withdrawal, the cash balance updates for the above withdrawal look as follows.
Example of the cash balance before the withdrawal request
{
"account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c",
"currency": "EUR",
"balance": "200",
"locked_for_trading": "0",
"pending_settlement": "0",
"available_for_withdrawal": "200",
"available_for_trading": "0"
}Example update for withdrawal NEW
{
"id": "a59c81ee-7770-4f6b-9ebe-8c268b78beb4",
"created_at": "2021-07-22T14:12:00.00Z",
"type": "CASH_BALANCE.UPDATED",
"object": {
"account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c",
"currency": "EUR",
"balance": "200",
"locked_for_trading": "0",
"pending_settlement": "0",
"available_for_withdrawal": "0",
"available_for_trading": "0"
},
"webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}Example update for withdrawal CONFIRMED
{
"id": "8c049f77-dc72-489d-8f5f-3871db782252",
"created_at": "2021-07-21T14:11:00.00Z",
"type": "CASH_BALANCE.UPDATED",
"object": {
"account_group_id": "d0fc0305-97b7-4e3b-bddf-66d3c434898c",
"currency": "EUR",
"balance": "0",
"locked_for_trading": "0",
"pending_settlement": "0",
"available_for_withdrawal": "0",
"available_for_trading": "0"
},
"webhook_id": "9df39835-be87-4243-9018-f2500b39cee6"
}There is no cash balance update for a nominal buy order with status PROCESSING, because all fields remain unaffected and do not change.
It is possible to cancel a withdrawal. The prerequisite for this is that they have the status NEW.
To cancel an existing withdrawal, call the cancellation endpoint with the appropriate withdrawal ID, using