Create a balance account

post/balanceAccounts

API Version

Creates a balance account that holds the funds of the associated account holder.

Endpoint destination URL

https://balanceplatform-api-test.adyen.com/bcl/v1/balanceAccounts

Request Parameters

Required

Optional

The unique identifier of the account holder associated with the balance account.

The default three-character ISO currency code of the balance account. The default value is EUR.

Max length: 300

A human-readable description of the balance account, maximum 300 characters. You can use this parameter to distinguish between multiple balance accounts under an account holder.

Max length: 150

Your reference for the balance account, maximum 150 characters.

Contains key-value pairs that specify configurations for balance sweeps per currency code. A sweep pulls in or pushes out funds based on a defined schedule, amount, and a source (for pulling funds) or a destination (for pushing funds).

The key must be a three-character ISO currency code in uppercase. For example, EUR. The value must be an object containing the sweep configuration.

The unique identifier of the destination or source balance account.

You can only use this for periodic sweep schedules such as schedule.type daily or monthly.

The merchant account that will be the source of funds. You can only use this if you are processing payments with Adyen. This can only be used for sweeps of type pull and schedule.type balance.

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.

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.

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

The unique identifier of the destination or source transfer instrument.

You can also use this in combination with a merchantAccount and a type pull to start a direct debit request from the source transfer instrument. To use this feature, reach out to your Adyen contact.

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.

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.

The time zone of the balance account. For example, Europe/Amsterdam. Defaults to the time zone of the account holder if no time zone is set. For possible values, see the list of time zone codes.

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.
accountHolderIdstring
The unique identifier of the account holder associated with the balance account.
balancesarray[object]
List of balances with the amount and currency.
availableinteger
The remaining amount available for spending.
balanceinteger
The total amount in the balance.
currencystring
The three-character ISO currency code of the balance.
reservedinteger
The amount reserved for payments that have been authorised, but have not been captured yet.
defaultCurrencyCodestring
The default three-character ISO currency code of the balance account. The default value is EUR.
descriptionstring
Max length: 300
A human-readable description of the balance account, maximum 300 characters. You can use this parameter to distinguish between multiple balance accounts under an account holder.
idstring
The unique identifier of the balance account.
paymentInstrumentsarray[object]
List of payment instruments associated with the balance account.
idstring
The unique identifier of the payment instrument.
referencestring
Max length: 150
Your reference for the balance account, maximum 150 characters.
statusstring
The status of the balance account, set to Active by default.

sweepConfigurationsobject
Contains key-value pairs that specify configurations for balance sweeps per currency code. A sweep pulls in or pushes out funds based on a defined schedule, amount, and a source (for pulling funds) or a destination (for pushing funds).

The key must be a three-character ISO currency code in uppercase. For example, EUR. The value must be an object containing the sweep configuration.
balanceAccountIdstring
The unique identifier of the destination or source balance account.

You can only use this for periodic sweep schedules such as schedule.type daily or monthly.
idstring
The unique identifier of the sweep.
merchantAccountstring
The merchant account that will be the source of funds. You can only use this if you are processing payments with Adyen. This can only be used for sweeps of type pull and schedule.type balance.
schedule
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.
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.
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.
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
transferInstrumentIdstring
The unique identifier of the destination or source transfer instrument.

You can also use this in combination with a merchantAccount and a type pull to start a direct debit request from the source transfer instrument. To use this feature, reach out to your Adyen contact.
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.

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.

timeZonestring
The time zone of the balance account. For example, Europe/Amsterdam. Defaults to the time zone of the account holder if no time zone is set. For possible values, see the list of time zone codes.
400 - Bad Request
A problem reading or understanding the request.
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.
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.
pathsarray[object]
contentarray[string]
rootPathobject
contentarray[string]
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.
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.
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.
pathsarray[object]
contentarray[string]
rootPathobject
contentarray[string]
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.
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.
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.
pathsarray[object]
contentarray[string]
rootPathobject
contentarray[string]
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.
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.
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.
pathsarray[object]
contentarray[string]
rootPathobject
contentarray[string]
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.
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.
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.
pathsarray[object]
contentarray[string]
rootPathobject
contentarray[string]
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 balance account

HTTP Responses

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

422 - Unprocessable Entity

500 - Internal Server Error