Balance

The balance flow can be used to acquire detailed information about the balance of one of the consumer’s accounts.

NOTE: The consent-usage is not available for all accounts. Please check the capabitilies of the account to see if it's available. The latest account_id and capabilities can be fetched via the consent accounts endpoint.

Request

POST /xs2a/v1/consents/{consent-id}/balances/get HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Token <Token>
Host: <Host>
{
    "consent_token": String,
    "account_id": String,
    "psu": ?{
        "user_agent": String,
        "ip_address": String,
    }
}

consent_token String, required

The consent_token can be obtained as described here.

account_id String, required

The account identifier provided in the result from an accounts request (from either the XS2A API or the Consent API) has to be passed in the payload of the request. The id of an account can change and it is recommended to request an updated list of accounts in order to use the latest ids.

psu Object, optional

The psu object is optional, however, if the consumer is present, it is recommended to provide it. Some banks soften their daily consent usage restrictions if the PSU data is available.

psu.user_agent String, required

The user_agent property holds the user agent string of the consumer's client application, e.g. the web browser.

psu.ip_address String, required

The ip_address property holds the IP address of the consumer. Both IPv4 and IPv6 are accepted formats.

Response

{
    "data": {
        "result": ?{
            "balance": ?Amount,
            "available": ?Amount,
            "limit": ?Amount,
            "reserved": ?Amount
        },
        "consent_token": String
    }
}

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 - reserved.

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.

data.consent_token String, always present

The response contains a new consent_token that has to be used in the following request.

NOTE: The returned information can differ depending on the selected bank, as some banks provide more information than others.

Example

Request

POST /xs2a/v1/consents/gp4cb0g6d9r3qf4d68fkrlb7ejo8mqqk/balances/get

{
    "consent_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6IjEyMzQ1Njc4OTAifQ.na71ipK8ASvggoM6C5vMjBKgJlZLxV-m6ElgHBrNtlU",
    "account_id": "fdff8f6f-d923-4489-90b3-43d11c021e1b",
    "psu": {
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.162 Safari/537.36",
        "ip_address": "192.168.2.1",
    }
}

Example Responses

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.

200 OK

{
    "data": {
        "result": {
            "balance": {
                "amount": 200,
                "currency": "EUR"
            },
            "available": {
                "amount": 270,
                "currency": "EUR"
            },
            "limit": {
                "amount": 100,
                "currency": "EUR"
            },
            "reserved": {
                "amount": 30,
                "currency": "EUR"
            }
        },
        "consent_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6Ijg4OTk3Nzg4In0.QQscn9a6-nQXuVK4Rwbft_LFMF3-r2xzWROEZMS2lW0"
    }
}

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": {
        "result": {
            "balance": {
                "amount": 200,
                "currency": "EUR"
            },
            "available": {
                "amount": 270,
                "currency": "EUR"
            }
        },
        "consent_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6Ijg4OTk3Nzg4In0.QQscn9a6-nQXuVK4Rwbft_LFMF3-r2xzWROEZMS2lW0"
    }
}

results matching ""

    No results matching ""