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.

Request Body Structure of a Balance Flow

{
    "iban": ?String,
    "account_id": ?String,
    "allowed_accounts": ?AllowedAccounts
}

iban String, optional

The IBAN of the account for which the balance flow should be executed.

account_id String, optional

The account identifier - as provided in the result of an accounts flow - of the account for which the balance flow should be executed.

allowed_accounts AllowedAccounts, optional

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
        }
    }
}

data.result.type String, always present

For successful flows the type property always holds the value balances.

data.result.account Account, always present

The account property holds the available details of the account.

data.result.balance Amount, optional

The balance property holds the actual balance of the account.

data.result.available Amount, optional

The available property holds the amount that is available for a transfer.

Typically available = balance + limit - resevered.

data.result.limit Amount, optional

The limit property holds the amount that represents the overdraft for the account, the additional amount the consumer can withdraw beyond 0.

data.result.reserved Amount, optional

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 resevered 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"
            }
        }
    }
}

results matching ""

    No results matching ""