Create a sweep

post/balanceAccounts/{balanceAccountId}/sweeps

Creates a sweep that results in moving funds from or to a balance account.

A sweep pulls in or pushes out funds based on a defined schedule, amount, currency, and a source or a destination.

Endpoint destination URL

https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/{balanceAccountId}/sweeps

Path Parameters

Required

Optional

The unique identifier of the balance account.

Request Parameters

Required

Optional

The type of transfer that results from the sweep.

Possible values:

bank: Sweep to a transfer instrument.
internal: Transfer to another balance account within your platform.

Required when setting priorities.

The destination or the source of the funds, depending on the sweep type.

Either a balanceAccountId, transferInstrumentId, or merchantAccount is required.

Show children

The three-character ISO currency code in uppercase. For example, EUR.

The sweep currency must match any of the balances currencies.

The message that will be used in the sweep transfer's description body with a maximum length of 140 characters.

If the message is longer after replacing placeholders, the message will be cut off at 140 characters.

The list of priorities for the bank transfer. This sets the speed at which the transfer is sent and the fees that you have to pay. You can provide multiple priorities. Adyen will try to pay out using the priority you list first. If that's not possible, it moves on to the next option in the order of your provided priorities.

Possible values:

regular: for normal, low-value transactions.
fast: a faster way to transfer funds, but the fees are higher. Recommended for high-priority, low-value transactions.
wire: the fastest way to transfer funds, but this has the highest fees. Recommended for high-priority, high-value transactions.
instant: for instant funds transfers in SEPA countries.
crossBorder: for high-value transfers to a recipient in a different country.
internal: for transfers to an Adyen-issued business bank account (by bank account number/IBAN).

Set category to bank. For more details, see optional priorities setup for marketplaces or platforms.

Max length: 80

Your reference for the sweep configuration.

Max length: 80

The reference sent to or received from the counterparty. Only alphanumeric characters are allowed.

The schedule when the triggerAmount is evaluated. If the balance meets the threshold, funds are pushed out of or pulled in to the balance account.

Show children

The status of the sweep. If not provided, by default, this is set to active.

Possible values:

active: the sweep is enabled and funds will be pulled in or pushed out based on the defined configuration.
inactive: the sweep is disabled and cannot be triggered.

The amount that must be pushed out or pulled in. You can configure either sweepAmount or targetAmount, not both.

Show children

The amount that must be available in the balance account after the sweep. You can configure either sweepAmount or targetAmount, not both.

Show children

The threshold amount that triggers the sweep. If not provided, by default, the amount is set to zero. The triggerAmount is evaluated according to the specified schedule.type.

For type pull, if the balance is less than or equal to the triggerAmount, funds are pulled in to the balance account.
For type push, if the balance is more than or equal to the triggerAmount, funds are pushed out of the balance account.

Show children

The direction of sweep, whether pushing out or pulling in funds to the balance account. If not provided, by default, this is set to push.

Possible values:

push: push out funds to a destination balance account or transfer instrument.
pull: pull in funds from a source merchant account, transfer instrument, or balance account.

Response parameters

After submitting a call, you receive a response message to inform you that your request was received and processed.

Depending on the HTTP status code of the response message, it is helpful to build some logic to handle any errors that a request or the system may return.

HTTP Responses

200 - OK
The request has succeeded.
Show moreShow less
categorystring
The type of transfer that results from the sweep.

Possible values:

bank: Sweep to a transfer instrument.

internal: Transfer to another balance account within your platform.

Required when setting priorities.
counterpartyobject
The destination or the source of the funds, depending on the sweep type.

Either a balanceAccountId, transferInstrumentId, or merchantAccount is required.
Show children Hide children
balanceAccountIdstring
The unique identifier of the destination or source balance account.

If you are updating the counterparty from a transfer instrument to a balance account, set transferInstrumentId to null.

merchantAccountstring
The merchant account that will be the source of funds.

You can only use this parameter with sweeps of type pull and if you are processing payments with Adyen.
transferInstrumentIdstring
The unique identifier of the destination or source transfer instrument depending on the sweep type

. To set up automated top-up sweeps to balance accounts in your marketplace or platform, use this parameter in combination with a merchantAccount and a sweep type of pull.

Top-up sweeps start a direct debit request from the source transfer instrument. Contact Adyen Support to enable this feature.> If you are updating the counterparty from a balance account to a transfer instrument, set balanceAccountId to null.
currencystring
The three-character ISO currency code in uppercase. For example, EUR.

The sweep currency must match any of the balances currencies.
descriptionstring
The message that will be used in the sweep transfer's description body with a maximum length of 140 characters.

If the message is longer after replacing placeholders, the message will be cut off at 140 characters.
idstring
The unique identifier of the sweep.
prioritiesarray[string]
The list of priorities for the bank transfer. This sets the speed at which the transfer is sent and the fees that you have to pay. You can provide multiple priorities. Adyen will try to pay out using the priority you list first. If that's not possible, it moves on to the next option in the order of your provided priorities.

Possible values:

regular: for normal, low-value transactions.

fast: a faster way to transfer funds, but the fees are higher. Recommended for high-priority, low-value transactions.

wire: the fastest way to transfer funds, but this has the highest fees. Recommended for high-priority, high-value transactions.

instant: for instant funds transfers in SEPA countries.

crossBorder: for high-value transfers to a recipient in a different country.

internal: for transfers to an Adyen-issued business bank account (by bank account number/IBAN).

Set category to bank. For more details, see optional priorities setup for marketplaces or platforms.
reasonstring
The reason for disabling the sweep.
reasonDetailstring
The human readable reason for disabling the sweep.
referencestring
Max length: 80
Your reference for the sweep configuration.
referenceForBeneficiarystring
Max length: 80
The reference sent to or received from the counterparty. Only alphanumeric characters are allowed.
scheduleobject
The schedule when the triggerAmount is evaluated. If the balance meets the threshold, funds are pushed out of or pulled in to the balance account.
Show children Hide children
cronExpressionstring
A cron expression that is used to set the sweep schedule. The schedule uses the time zone of the balance account. For example, 30 17 * * MON schedules a sweep every Monday at 17:30.

The expression must have five values separated by a single space in the following order:

Minute: 0-59

Hour: 0-23

Day of the month: 1-31

Month: 1-12 or JAN-DEC

Day of the week: 0-7 (0 and 7 are Sunday) or MON-SUN.

The following non-standard characters are supported: *, L, #, W and /. See crontab guru for more examples.

Required when type is cron.

typestring
The schedule type.

Possible values:

cron: push out funds based on a cronExpression.

daily: push out funds daily at 07:00 AM CET.

weekly: push out funds every Monday at 07:00 AM CET.

monthly: push out funds every first of the month at 07:00 AM CET.

balance: execute the sweep instantly if the triggerAmount is reached.

statusstring
The status of the sweep. If not provided, by default, this is set to active.

Possible values:

active: the sweep is enabled and funds will be pulled in or pushed out based on the defined configuration.

inactive: the sweep is disabled and cannot be triggered.

sweepAmountobject
The amount that must be pushed out or pulled in. You can configure either sweepAmount or targetAmount, not both.
Show children Hide children
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
targetAmountobject
The amount that must be available in the balance account after the sweep. You can configure either sweepAmount or targetAmount, not both.
Show children Hide children
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
triggerAmountobject
The threshold amount that triggers the sweep. If not provided, by default, the amount is set to zero. The triggerAmount is evaluated according to the specified schedule.type.

For type pull, if the balance is less than or equal to the triggerAmount, funds are pulled in to the balance account.

For type push, if the balance is more than or equal to the triggerAmount, funds are pushed out of the balance account.

Show children Hide children
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
typestring
The direction of sweep, whether pushing out or pulling in funds to the balance account. If not provided, by default, this is set to push.

Possible values:

push: push out funds to a destination balance account or transfer instrument.

pull: pull in funds from a source merchant account, transfer instrument, or balance account.
400 - Bad Request
A problem reading or understanding the request.
Show more Show less
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
Show children Hide children
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
401 - Unauthorized
Authentication required.
Show more Show less
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
Show children Hide children
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
403 - Forbidden
Insufficient permissions to process the request.
Show more Show less
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
Show children Hide children
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
422 - Unprocessable Entity
A request validation error.
Show more Show less
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
Show children Hide children
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
500 - Internal Server Error
The server could not process the request.
Show more Show less
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
Show children Hide children
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.

Create a sweep

Path Parameters

Request Parameters

Response parameters

HTTP Responses

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

422 - Unprocessable Entity

500 - Internal Server Error