Operating Model:
Operating Model:

Cash balance withdrawal

A withdrawal is the process of paying out a user’s funds to their reference account.

How withdrawals work

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:

  1. Once a sell order is successfully executed, the Investment API calculates the net amount after taxes and fees.
  2. A user’s cash balance is updated by the net amount and assigned the state PENDING_SETTLEMENT.
  3. After the order is settled funds are transferred to the user's cash account in our system, representing a funding event.
  4. 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:

Cash withdrawal

INFO

Settlement of funds typically takes two business days.

How to implement withdrawals

Prerequisites

Withdrawals require that a user is created, has an assigned reference bank account, and sufficient funds in their cash balance (e.g., from a sell order) that are not locked for other purposes such as re-investment.

Submitting a withdrawal request

To request a cash withdrawal, you can specify the cash amount and reference account when triggering a request by POST /payments/withdrawals

Example request

{
    "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",
    "remittance_information": "Withdrawal"
}

After a successful withdrawals request, the sample response for the above will look as follows:

Example response

{
    "id": "6ffa6b16-2380-4e7a-88b2-ae625c8eef99",
    "created_at": "2020-08-24T14:15:22Z",
    "updated_at": "2020-08-24T14:15:22Z",
    "reference_account_id": "295378ec-036e-4f3f-ae5c-2be85c93e837",
    "account_group_id": "ac1c39e9-2101-46b8-a624-d10a9e351b6c",
    "user_id": "b668282b-cdf3-439a-bda2-3f3c9f655bb7",
    "amount": "200.00",
    "currency": "EUR",
    "remittance_information": "Withdrawal",
    "status": "NEW"
}

You will also receive a withdrawal NEW webhook with the exactly same payload.

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.

Cash balance update

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

INFO

There is no cash balance update for a nominal buy order with status PROCESSING, because all fields remain unaffected and do not change.

Was this page helpful?