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.

Webhooks notify you of events in busines 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 POST request. This is the only reliable way to know if the call has failed and should be re-requested.

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:

Parameter	Expected Information	Example
amount	`<topup_amount>`	200.00
remittance_information	topup `<settlement_reference>`	topup 1ab4fef9-a097-4c6f-9345-647025d5fde6

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.

Details of the beneficiary account information will be provided in advance.

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

Cancelling a top-up

Top-ups can only be cancelled if they have the status NEW or CONFIRMED.

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.