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.
Before you begin
Before you can top up your users' balance accounts on demand, you must:
-
Contact our Support Team to enable on-demand top-ups for your marketplace.
-
Ensure that your server can receive and accept webhooks.
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.
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.