Top-ups

In this guide, we introduce you to the powerful top-ups feature, which allows users to invest as quickly as possible by increasing their available cash balance. With top-ups, users can seamlessly invest in assets without having to wait for their funds to settle, making investing more efficient and convenient.

How top-ups work

Top-ups enable a smooth investment process as the funds are available when users need them. This also means that users do not miss out on investment opportunities.

Generally, top-ups processes are completed in real time and settlement of funds is expected at a later date, allowing users to invest immediately without having to wait for funds to be released.

The workflow for top-ups usually looks like this:

1. The client sends a top-up request on behalf of their users. For example, after the placement of an order.

2. Upvest increases the credit balance of the account group by the desired amount in real time.

3. The client later ensures for the transfer and settlement of top-up cash amount in the Upvest bank account.

Process overview

The following flow diagram illustrates the flow including all related status changes, and cash balance updates:

Implementing top-ups

Prerequisites

Before triggering a top-up request, you must ensure that the user is onboarded and active.

Submitting a top-up request

To request a top-up, specify the funding amount for the user’s account group, then trigger the top-up by

POST /payments/topups.

Example request

{
    "account_group_id": "1ea60f56-b67b-61fc-829a-0242ac130003",
    "cash_amount": "200.00",
    "currency": "EUR"
}

After a successful top-up request, the following response is returned:

Example response

{
    "id": "1ab4fef9-a097-4c6f-9345-647025d5fde6",
    "created_at": "2020-08-24T14:15:22Z",
    "account_group_id": "1ea60f56-b67b-61fc-829a-0242ac130003",
    "cash_amount": "200.00",
    "currency": "EUR",
    "status": "CONFIRMED",
    "settlement_reference": "1ab4fef9-a097-4c6f-9345-647025d5fde6"
}

You will also receive a top-up CONFIRMED webhook with exactly the same payload.

Cash balance update

Immediately after confirming a top-up request, you will also receive a cash balance updated event via webhook.

Settlement of top-up

To settle a top-up request, the client must make a payment to a pre-determined bank account managed by Upvest. The payment should include the total payment amount, along with remittance information indicating which top-up is to be settled. Below is a table showing what payments can be expected to settle a top-up request, including an example based on the previous request:

By adhering to this specific payment pattern, we can ensure that the settlement process is efficient and streamlined, reducing the likelihood of errors or delays. It is important that clients follow the instructions carefully to ensure that their top-up request is processed on time and correctly.

Once the cash settlement has been received and processed, you will receive a top-up SETTLED webhook.