Classic-platform icon

Top up funds in accounts

Let account holders add funds to their account by debiting directly from their bank account.

This page is for classic Adyen for Platforms integrations. If you are just starting your implementation, refer to our new integration guide instead.

While the funds in account holders' accounts usually come from payments, you can also let them top up their accounts with direct debit.

Topping up funds in accounts is useful when:

  • Covering for possible negative balances, caused by refunds and chargebacks.
  • Debiting costs from bank accounts when account holders' accounts have insufficient funds.

Topping up funds is supported for account holders with bank accounts in the EU, the UK, and the US. The direct debit transactions are processed over corresponding standard debit rails of Single Euro Payments Area (SEPA), Bankers' Automated Clearing Services (BACS), and Automated Clearing House (ACH) network.

Before you begin

Make sure to:

  • Contact our Support Team to enable direct debits for your platform.
  • Have the account holder agree to your platform performing direct debits on their bank account.
  • When using ACH, business and non-profit account holders must contact their bank and request to allow direct debits from Adyen. Otherwise, banks might block the transactions.
    The bank must allow the following Company or Originator IDs: 2638633811, 9263863381, 8263863381, 4263863381, 3263863381, 2263863380.

Step 1: Make a direct debit request

To start a direct debit, send a POST /debitAccountHolder request specifying:

Parameter Required Description
accountHolderCode -white_check_mark- The code of the account holder.
amount -white_check_mark- The total amount to be debited. When debiting from bank accounts in the EU, the maximum amount is EUR 500 per transaction.
bankAccountUUID -white_check_mark- The identifier of the account holder's bank account from which funds are debited.
merchantAccount -white_check_mark- Your merchant account.
splits -white_check_mark- Array that contains your instructions on how to split the funds between the accounts in your platform. The array must have at least one item.
description Your description for the transaction, which you can use when reconciling the direct debit.

Here is an example of making a direct debit request for USD 62 split to two accounts: USD 60 to the account holder's account and USD 2 to your platform's liable account.

Requests using /debitAccountHolder are processed asynchronously. You'll receive a response acknowledging that we have received your request, but you must listen to notification webhooks to know the result.

Step 2. Check the direct debit result

Listen to the DIRECT_DEBIT_INITIATED notification webhook and refer to the status.statusCode to know the outcome of your request.

This webhook has two possible status codes:

  • Initiated: The direct debit has been initiated. As transactions are processed over standard debit rails of ACH, BACS, or SEPA, the funds settle to the accounts based on standard settlement times. Once settled, the transaction is included in reports.
  • Failed: The direct debit failed. You may receive this notification up to 3 business days after you sent the request. When a direct debit fails, the possible causes are:
    • Validation errors, such as the bankAccountUUID does not exist.
    • The transaction hit direct debit limits. For example, EUR 500 per transaction for SEPA.
    • The account holder failed to allow Adyen's Company or Originator IDs with their bank.
    • Adyen did not receive the funds.
    • Insufficient funds, or any other refusal from the bank.

Reconciling direct debits

Successful direct debits are settled to your Adyen merchant account. You can see these transactions in the Settlement details report with the Record Type MerchantPayin.

When funds are credited to the accounts based on split instructions, the credits are reported in the Marketplace Payments accounting report. Using this report, you can match the direct debits using the description you provided in the /debitAccountHolder request. The description is included as the Payment Merchant Reference.

See also