Implementing fee collection

Prerequisites

The following requirements apply:

 ✓   Fee collection endpoints are enabled
Details

In order to use the fee collection function, Upvest must activate the corresponding API endpoints for you.


 ✓   User must have accounts and account groups
Details

To collect fees from a cash balance or via cover purchase orders, the user must have an active account group and an account.

You can find out more about creating accounts and account groups here.


Fee collections

Fee collections describe the processing of fee amounts calculated in advance. The fee amounts can originate from fee calculations via the Investment API or from fees calculated by the client.

You can create, list and retrieve a fee collection.

   Creating a fee collection

If you have pre-calculated the amount for a fee, you can create a fee collection as follows:

POST /fees/collections

Example request

{
    "account_id": "689f7566-2ca3-4007-b99d-e501be8c7783",
    "type": "SERVICE_FEE",
    "collection_amount": "12.41",
    "currency": "EUR",
    "period_start": "2022-11-01",
    "period_end": "2022-11-30"
}
ParameterDescription
account_idRequired: The ID of the account on which the fees shall be charged.
typeRequired: Specify the type SERVICE_FEE for normal cadence fee collections or SERVICE_FEE_LIQUIDATION as a result of account liquidations.
collection_amountRequired: The pre-calculated amount of fees to be collected.
currencyRequired: Specify the currency. Currently, only EUR is supported.
period_startRequired: Start date of the fees calculated.
period_endRequired: End date of the fees calculated.

You will receive a fee collection object with the fee collection ID in the response.

INFO

Please note you may only start a fee collection process on accounts that are not in PENDING_APPROVAL or CLOSED statuses. Should the account be in a PENDING_APPROVAL or CLOSED status, a Bad Request response code will be returned. Otherwise, you will receive a fee collection object with fee collection ID in the response.


   Monitoring your fee collections

Once a fee collection processes has been created, you will recieve fee collection events as webhooks. These events will notify you in changes in status of the fee collection entity. You'll recieve webhooks for each of the following statuses:

StatusDescription
FEE_COLLECTION.CREATEDThe fee collection is in progress.
FEE_COLLECTION.FINALISEDThe fee collection is finalised - fees have been collected from the account and the funds have been transferred to the client.
FEE_COLLECTION.CANCELLEDThe fee collection is cancelled.

   Listing fee collections

To retrieve all fee collections make the following request:

GET /fees/collections.

You can retrieve a fee collection with its specific fee_collection_id as follows:

GET /fees/collections/{fee_collection_id}

Fee collection status

The following statuses apply to a fee collection:

StatusDescription
PROCESSINGThe fee collection is in progress.
FINALISEDThe fee collection is finalised - fees have been collected from the account and the funds have been transferred to the client.
CANCELLEDThe fee collection is cancelled.

   Reporting on fee collections

Webhooks for potential sell-to-cover orders, cash balance updates and the financial transaction reporting of the type FEE_COLLECTION are available. The transaction reporting webhook and object contains a reference to the fee collection object for additional details.

   Complete

Next steps

Gain further insight into fee collection by reading about our transaction reporting functionality.

Was this page helpful?