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.

Cancelling a top-up

To cancel an existing top-up, call the cancellation endpoint with the corresponding topup_id, using

DELETE /payments/topups/{topupID}

It is possible to cancel a top-up. The prerequisite for this is that they have the status NEW or CONFIRMED.