Pesquisar

Are you looking for test card numbers?

Would you like to contact support?

Atenção, esta página não se encontra disponível em Português
Marketpay icon

Top up funds in accounts

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

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: 9263863381, 8263863381, 4263863381, 3263863381, 2263863380.

Step 1: Make a direct debit request

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

Direct debit request
curl https://cal-test.adyen.com/cal/services/Fund/v6/debitAccountHolder \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
   "accountHolderCode": "ACCOUNT_HOLDER_CODE",
   "description": "YOUR_DESCRIPTION",
   "bankAccountUUID": "000b81aa-ae7e-4492-aa7e-72b2129dce0c",
   "amount": {
     "value": 6200,
     "currency": "USD"
   },
   "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
   "splits": [
     {
       "amount": {
         "value": 6000
       },
       "type": "MarketPlace",
       "account": "8535516988037431",
       "reference": "YOUR_SPLIT_REFERENCE_1",
     },
     {
       "amount": {
         "value": 200
       },
       "type": "Commission",
       "reference": "YOUR_SPLIT_REFERENCE_2"
     }
   ]
 }'
Direct debit response
{
  "pspReference":"8515681150749298",
  "resultCode":"Received",
  "accountHolderCode":"ACCOUNT_HOLDER_CODE",
  "bankAccountUUID":"000b81aa-ae7e-4492-aa7e-72b2129dce0c",
  "merchantReferences":["YOUR_SPLIT_REFERENCE_1","YOUR_SPLIT_REFERENCE_2"]
}

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, 1000 EUR 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.
Direct debit initiated
{
    "eventDate": "2021-02-01T14:19:14-08:00",
    "eventType": "DIRECT_DEBIT_INITIATED",
    "live": "false",
    "pspReference": "8515681150749298",
    "content": {
        "accountCode": "8825579787887769",
        "amount": {
            "currency": "USD",
            "value": 6200
        },
        "debitInitiationDate": "2021-02-01",
        "splits": [
            {
                "account": "8535516988037431",
                "amount": {
                    "currency": "EUR",
                    "value": 6000
                },
                "reference": "YOUR_SPLIT_REFERENCE_1",
                "type": "MarketPlace",

            },
            {
                "amount": {
                    "currency": "EUR",
                    "value": 200
                },
                "reference": "YOUR_SPLIT_REFERENCE_2",
                "type": "Commission",
            }
        ],
        "status": {
            "statusCode": "Initiated"
        }
    }
}
Direct debit failed
{
    "eventDate": "2021-07-07T16:30:37+02:00",
    "eventType": "DIRECT_DEBIT_INITIATED",
    "live": "false",
    "pspReference": "8315659584588245",
    "content": {
        "accountCode": "8825579787887769",
        "amount": {
            "currency": "EUR",
            "value": 500000
        },
        "debitInitiationDate": "2021-07-07",
        "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT",
        "splits": [
            {
                "account": "8535516988037431",
                "amount": {
                    "currency": "EUR",
                    "value": 490000
                },
                "reference": "YOUR_SPLIT_REFERENCE_1",
                "type": "MarketPlace"
            },
            {
                "amount": {
                    "currency": "EUR",
                    "value": 10000
                },
                "reference": "YOUR_SPLIT_REFERENCE_2",
                "type": "Commission"
            }
        ],
        "status": {
            "message": {
                "code": "10_145",
                "text": "Failed to initiate the direct debit for account holder."
            },
            "statusCode": "Failed"
        }
    }
}

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