Balance
The balance flow can be used to acquire detailed information about the balance of one of the consumer’s accounts.
Once the flow is finished one Balance object can be obtained. The information provided can differ depending on the selected bank, as some banks provide more information than others.
In order to request the balance of a specific account, the account identifier or the IBAN can be passed in the payload of the request. If neither the identifier nor the IBAN is set the consumer has to select an account, if more than one account is present.
The flow is not available for all accounts. Please check the capabitilies of the account to see if it's available.
Request Body Structure of a Balance Flow
{
"iban": ?String,
"account_id": ?String,
"account_number": ?String,
"allowed_accounts": ?AllowedAccounts
}
The account identifier - as provided in the result of an accounts flow - of the account for which the balance flow should be executed.
The account number - as provided in the result of an accounts flow - of the account for which the balance flow should be executed.
A configuration for filtering the options at the account selection for the consumer.
This can't be used in combination with the iban and account_id fields.
Response Structure of a successful Balance Flow
{
"data": {
"state": Enum<'PROCESSING', 'CONSUMER_INPUT_NEEDED', 'ABORTED', 'EXCEPTION', 'FINISHED'>,
"result": ?{
"type": String,
"account": Account,
"balance": ?Amount,
"available": ?Amount,
"limit": ?Amount,
"reserved": ?Amount
}
}
}
For successful flows the type property always holds the value balances.
The account property holds the available details of the account.
The available property holds the amount that is available for a transfer.
Typically available = balance + limit - reserved.
The limit property holds the amount that represents the overdraft for the account, the additional amount the consumer can withdraw beyond 0.
The reserved property holds the amount that is reserved for known future payments.
Example Responses for a successful Balance Flow
In this example, the account has a balance of 200 EUR, a limit of 100 EUR and 30 EUR reserved for future payments which results in 270 EUR available for transfers.
{
"data": {
"state": "FINISHED",
"result": {
"type": "balances",
"account": {
"id": "123e4567-e89b-12d3-a456-426655440000",
"alias": "Girokonto",
"account_number": "123456789",
"iban": "DE44500105175407324931",
"holder_name": "Max Mustermann",
"bank_code": "51091700",
"bic": "VRBUDE51XXX",
"bank_name": "VR Bank Untertaunus eG",
"transfer_type": "FULL",
"account_type": "DEFAULT",
"balance": {
"amount": 200,
"currency": "EUR"
}
},
"balance": {
"amount": 200,
"currency": "EUR"
},
"available": {
"amount": 270,
"currency": "EUR"
},
"limit": {
"amount": 100,
"currency": "EUR"
},
"reserved": {
"amount": 30,
"currency": "EUR"
}
}
}
}
Banks typically do not return all types of balances. It is more common to only receive balance and/or available. In addition, the balances can vary depending on the bank. In case a bank only shares available and no other balance, it can mean that this is the actual balance of the account. However, the balance shared is most likely the one the account holder is familiar with. Therefore a more realistic example is shown below.
{
"data": {
"state": "FINISHED",
"result": {
"type": "balances",
"account": {
"id": "123e4567-e89b-12d3-a456-426655440000",
"alias": "Girokonto",
"account_number": "123456789",
"iban": "DE44500105175407324931",
"holder_name": "Max Mustermann",
"bank_code": "51091700",
"bic": "VRBUDE51XXX",
"bank_name": "VR Bank Untertaunus eG",
"transfer_type": "FULL",
"account_type": "DEFAULT",
"balance": {
"amount": 200,
"currency": "EUR"
}
},
"balance": {
"amount": 200,
"currency": "EUR"
},
"available": {
"amount": 270,
"currency": "EUR"
}
}
}
}