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:
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
.
Was this page helpful?