Adyen-for-platform icon

Top up on demand

Make payment requests to top up balance accounts on demand.

You can submit requests to manually top-up your users' balance accounts when needed. In this case, you create a one-off payment funded by your user, that increases the balance in their balance account.

Requirements

Before you can top up your users' balance accounts on demand, you must:

Fund the top-up

Top-ups of your users' balance account are usually funded by your users themselves.

Your users can fund the top-up of their balance accounts in the following ways:

Option 1: Using their verified transfer instrument

  • The following capabilities must be allowed for your user, and have a valid verificationStatus:

    • receiveFromPlatformPayments
    • receiveFromTransferInstrument
  • Your user must have a verified transfer instrument in the EU, the UK, or the US. You cannot fund a top-up with transfer instruments from other regions.

Option 2: Using any other payment method

Make sure that following capability is allowed for your user, and has a valid verificationStatus: receiveFromPlatformPayments

Differentiate the top-up

When you process a payment to top up a balance account, you can include instructions to define the top-up and differentiate it from regular payments. This allows you to:

  • Reconcile top-ups separately from other payments using our reports.
  • For users based in the US, exclude top-ups from tax filings. Top-ups do not count towards your user's revenue, and are not included in the 1099-K tax forms.

When you provide instructions to define the top-up, you can also specify where to book the top-up amount and the transaction fees it incurs.

Make a top-up request

To top-up a balance account on demand, make a POST /payments request for the amount you want to top up.

You cannot initiate a top-up using a /sessions request.

The following tabs show you how to initiate a top using your user's transfer instrument or another payment method.

In your payment request, specify the following fields:

Parameter Required Description
amount.currency -white_check_mark-
Required for currency conversion.
The currency of the top-up.
amount.value -white_check_mark- The value of the top-up.
merchantAccount -white_check_mark- Your merchant account name.
reference -white_check_mark- Your unique reference for this payment.
returnUrl -white_check_mark- URL to where the shopper should be taken back to after a redirection. The URL can contain a maximum of 1024 characters and should include the protocol: http:// or https://. You can also include your own additional query parameters, for example, shopper ID or order reference number.
paymentMethod.type -white_check_mark- The type of payment method. Possible values:
  • ach: for payments from verified bank accounts in the US, made in USD.
  • sepadirectdebit: for payments from verified bank accounts in the EU, made in EUR.
  • directdebit_GB: for payments from verified bank accounts in the UK, made in GBP.
paymentMethod.transferInstrumentId -white_check_mark- The unique identifier of your user's verified transfer instrument.
splits An array containing instructions for each split of the total payment amount. You can define instructions for the top-up here.

If you do not include a splits array, the funds are booked to your liable account, and classified as a regular payment.

Splits array

To define the top-up and differentiate it from regular payments, include the following objects in your splits array:

In each object within the array, specify:

Parameter Required Description
splits.type -white_check_mark- Defines the top-up and the transaction fees.
splits.account The balance account that is credited or debited.
  • Top-up amount: the unique identifier of the balance account you want to top up.
  • Transaction fees: the unique identifier of the balance account to which you want to book the fees.
splits.amount.value -white_check_mark-
Required for the top-up object
The amount of the top-up. You do not need to specify this field for the transaction fees object, because they are not known at the time of payment.

Here is an example of a POST /payments request to top up your user's balance account with EUR 100.00 using their transfer instrument with ID SE00000000000000000000001. In this example, your user is based in the EU.

Top-up request using a transfer instrument from the EU
Expand view
Copy link to code block
Copy code
Copy code
curl https://checkout-test.adyen.com/v71/payments \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-X POST \
-d '{
"paymentMethod": {
"type": "sepadirectdebit",
"transferInstrumentId": "SE00000000000000000000001"
},
"amount": {
"value": 10000,
"currency": "EUR"
},
"reference": "YOUR_ORDER_NUMBER",
"merchantAccount": "YOUR_MERCHANT_ACCOUNT",
"returnUrl": "https://your-company.com/...",
"splits": [
{
"amount": {
"value": 10000
},
"type": "TopUp",
"account": "BA00000000000000000000001",
"reference": "Your reference for the top-up.",
"description": "Your description for the top-up."
},
{
"type": "PaymentFee",
"account": "BA00000000000000000000001",
"reference": "Your reference for the transaction fees.",
"description": "Your description for the transaction fees."
}
]
}'

After you make the request, you receive the following response:

Response
Expand view
Copy link to code block
Copy code
Copy code
{
"additionalData": {
"sepadirectdebit.dateOfSignature": "2024-05-02",
"sepadirectdebit.mandateId": "FJM726V375BV9D82",
"sepadirectdebit.sequenceType": "Recurring"
},
"pspReference": "QFQTPCQ8HXSKGK82",
"resultCode": "Authorised",
"amount": {
"currency": "EUR",
"value": 10000
},
"merchantReference": "YOUR_ORDER_NUMBER",
"paymentMethod": {
"type": "sepadirectdebit"
}
}

Get updates when a top-up is triggered

Use top-up webhooks to track incoming payment requests related to on-demand top-ups. These webhooks provide the status of the incoming payment request, from the time when Adyen received the request and the payment was authorised, up to when the funds were added to the balance account. These webhooks also inform you if the payment failed.