Fast-payout icon

Create recurring top-ups

Learn how to configure recurring top-ups for your balance accounts.

View source

You can create recurring top-ups to automatically pull funds into your balance accounts when needed. This ensures that your balance accounts are adequately funded and have sufficient balance for day-to-day activities.

A recurring top-up triggers outgoing direct debit requests to a bank account, based on the settings you configure. These settings determine the amount, frequency, and source of funds for the direct debit requests. Adyen then books the funds from the top-up to your balance account.

Requirements

Requirement Description
Integration type Adyen enterprise payouts integration.
API credential roles To configure top-up schedules using the API, make sure that you have the credentials for the Configuration API with the following role:
  • BankAPI Advanced Webservice role
Customer Area roles To configure top-up schedules using the Customer Area, make sure that you have the following roles:
  • Balance platform base role
  • Configure scheduled payouts
Webhooks Subscribe to the following webhooks:
Capabilities Make sure that the account holder has the following capability:
  • receiveFromTransferInstrument

Before attempting a transfer, verify that this capability is active and has a valid verificationStatus. You can check this via the verificationStatus.

Note, if you need to enable this capability see Request a capability.
Limitations
  • This feature does not support on-demand top-ups.
  • Top-ups are supported only in EUR and USD.
Setup steps

Create a recurring top-up

You can create a recurring top-up using the API or your Customer Area.

Processing and cut-off times

If you set a time-based schedule (such as weekly or monthly), the trigger timestamp defaults to 7:00 AM in the timezone of your account. Settle times depend on how this trigger time interacts with currency-specific cut-offs:

  • USD (T+2 settlement): Because the automatic 7:00 AM trigger occurs after the 01:45 ET cut-off, funds settle on T+2 (after 08:30 ET).
  • EUR (next business day settlement): Because the automatic 7:00 AM trigger occurs before the 14:00 CET cut-off, funds settle on the next business day.

Error messages and failure reasons

When you create top-up schedules using the API, if the request fails, the reason for the failure is provided in the API response. The following table shows how to identify and troubleshoot some of the most common errors that can occur during top-up creation.

Status Error code
errorCode		 Error summary
title		 Reason
detail
400 29_001 The request is missing required fields or contains invalid data. trigger.threshold.currency: missing or invalid currency code.
400 29_001 The request is missing required fields or contains invalid data. Currencies must match threshold currency.
  • topUpAmount.fixed.currency
  • topUpAmount.target.currency
400 29_001 The request is missing required fields or contains invalid data. description: invalid placeholders or invalid format.
404 1082_105 Recurring top-up not found. Top-up ID does not exist. (Applies to GET, PATCH, DELETE requests).
422 30_013 Balance account not found. Could not find balance account with ID {id}.
422 1082_101 Account top-up currency mismatch. Currency of the top-up does not match the balance account.
422 1082_102 Invalid BAP configuration provided. BAP property DirectDebitTopUp is not active for this balance account.
422 1082_103 Invalid recurring top-up request. Generic invalid request rejected by banksweep.
422 1082_104 Account is missing required capabilities. Missing receiveFromTransferInstrument on the account holder.
422 1082_107 Failed to resolve payment instrument. Payment instrument could not be resolved.
422 1082_108 Failed to resolve transfer instrument. Invalid transfer instrument with id {id}.
422 1082_112 No valid routes found. No routes are available for the provided configuration.
422 1082_113 No PPA route assigned. No PPA route found.
422 1082_114 Terms of service not signed. A terms of service needs to be signed before having a recurring top-up configured.
422 1082_115 Direct debit amount threshold exceeded. Top-up amount exceeds the configured maximum threshold for direct debit top-ups on balance account {id}.
422 1011_001 An account has an invalid status. BalanceAccountHolder {id} has invalid account status inactive.
422 1011_003 Invalid counterparty provided. Validation failed for one of the following reasons:
  • Cannot configure a sweep to itself.
  • Bank account id is invalid.
  • Merchant account not found.
  • Legal entity does not have access to transfer instrument.
422 1011_013 A sweep with this configuration already exists. A ({direction}) sweep with currency ({cur}), counterparty ({cp}) and schedule ({sched}) already exists: ({id}).

See also