Account API

Access account balance and transaction history of a customer in total security.

Introduction

AIS

These endpoints provide the possibility for an AISP to access the account information and transaction history of a Belfius/Banx payment account, provided the AISP has received the required token(s) generated as a result of the consent process.

Produces
  • application/json

Hosts

You can use the production host when you want to go live:

psd2.b2b.belfius.be:8443

psd2.b2b.banx.be:8443

Click the button below to download the open API specification.

Download

Example screen

Navigate to an endpoint to see sample code


Get authorized account details along with balance.

Returns the account-details and associated balance(s) for a given payment account that is specified by the AISP through an encrypted logical-id of the account. In case of a multi-currency account, the returned account balance is always a balance in euro. This balance is associated with the balance of the euro compartment or the globalised amount in euro of the balance of all compartments (depending on the parameter of the account). A list of each currency compartment with its balance is also provided in the API response.


Parameters

Response

{
  "product_type": "payment-account",
  "product_name": "compte beats new",
  "iban": "BE80350454678790",
  "currency": "EUR",
  "balance": "123.12",
  "multicurrency": "True",
  "account_name": "Account Name",
  "other_compartments": [
    {
      "currency": "EUR",
      "balance": -123.12
    }
  ],
  "psu_name": "Francois Dupont",
  "_links": {
    "self": {
      "href": "string",
      "templated": "boolean"
    },
    "transactions": {
      "href": "string",
      "templated": "boolean"
    }
  }
}
Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Get /accounts/{logical-id}

Request example

There is no example request provided

Response example

{
  "product_type": "payment-account",
  "product_name": "compte beats new",
  "iban": "BE80350454678790",
  "currency": "EUR",
  "balance": "123.12",
  "multicurrency": "True",
  "account_name": "Account Name",
  "other_compartments": [
    {
      "currency": "EUR",
      "balance": -123.12
    }
  ],
  "psu_name": "Francois Dupont",
  "_links": {
    "self": {
      "href": "string",
      "templated": "boolean"
    },
    "transactions": {
      "href": "string",
      "templated": "boolean"
    }
  }
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}

Get transactions for an authorized account.

Returns the booked transactions for a given payment account that is specified by the AISP through an encrypted logical-id for the account. The request may use some filter parameter in order to restrict the query, e.g. the attributes "date_from" and "date_to". The result may be subject to pagination (i.e. retrieving a partial result in case of having too many results) through a set of pages by the ASPSP. Thereafter, the AISP may ask for the next page of results.


Parameters

logical-id Path required string

Encrypted Logical ID of the account which is mapped to IBAN.

example:

"eyJ0eXAiOiJKV1QiLCJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0..nlCNeZS3793ce9amOpgZWA.GFvPUO37HZGjFIpUJ3G7z2ki1pP_2Q5m6LCWoZtGjZE.aLpigr_nQ1GvtZfdQ4h1Fw"
Authorization Header required string

The access token. Note that the access token is limited to a given type of request [here AIS] and given IBAN. The token itself should be passed as bearer token in the Authorization header, like: "Bearer 987tghjkiu6trfghjuytrghj".

example:

"Bearer 987tghjkiu6trfghjuytrghj"
Request-ID Header required string

The ID of the request. Must be unique. It has to be a valid UUID in V04 format.

example:

"99391c7e-ad88-49ec-a2ad-99ddcb1f7721"
Accept Header required string

It must be of type application/json including the API version number. [Accept:application/vnd.belfius.api+json; version=2].

example:

"application/vnd.belfius.api+json; version=2"
Accept-Language Header required string

Language. It can include a language in ISO 639-1 format [example: fr]. Note that during redirection, Belfius/Banx screens are only available in French (fr) and Dutch (nl).

example:

"fr"
Client-ID Header required string

The Client ID of a registered AISP, received after the onboarding.

example:

"l7957ffbdbcbf4496a8a406702aacbf539"
Redirect-URI Header required string

Redirect-URI from the AISP. URI to which Belfius/Banx will redirect the PSU after redirection in Belfius/Banx environment.

example:

"https://www.clientapp.com/someurl"
SCA-Token Header optional string

Conditional: SCA token to be passed as header. It is mandatory to be able to access the transactions older than 90 days from today [date_from < today - 90 days]. The SCA-token can be retrieved immediately after the account(s) enrolment or by using a separate SCA flow (please refer to the "flow" section for more information). The token itself is an encrypted JWT valid for 1 hour. Plese note that the SCA-token will be checked only if date_from is filled & meets the criteria of date_from < today - 90 days.

example:

"eyJ0eXAiOiJKV1QiLCJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0..vMYfeOeQxz-Ebd3Sl4mn-w.oAw-c_L_R8jjZrRT-BQUYRdVyrTW2uBTW8Gk4enOu7Dqo0JIYA1q3dcLSZznG8EHk_KUI96JwUGQ6-n695M94KfNmH9Y9QO-ItPvJj7b35uxHZjGcunQ3Qbm0n_r4tSGnrRzzpVKscKnnpf2RDPYtmjOUucJHx25A1-U5q_VZVOpfBFdx1v_is8vNqBp0zym11G2xuVHCwdDSXffZqzp8ovyV7FezbeJEfa9l49e2vN0KLGnOGWDjPnPmJuhRYC7ZxbFfJ7trNJAwb2qGordHO7rupi9RWqPb2Z8pv_qCHktwjiTKraW-edDaLW8VUOWiCB2-5cgy0cJcN9WWS0SepHqnaMH-tyYF7oR3cPMJVYtGHe8lQ5hojBo9Qi6N1CsCYu8LqVLhH0XVQo9qq1Y3zFRSgXeQ3LjLbH4g0zmbrj1lPgNyfb6EX1sQB0evHrF46P4oJ5E0wpeGeTClc_VNdPe0G7iSCWhVtgn3B8uUpdIWEsaYwtpndjWNqxXAH8wGaxyay-SfwmbiykvW01MlRrEpqdBTlBSy6iGzqSxREk.nJyqrxDoAll2a7XJgrlnFg"
psu_involved Query optional boolean

If present (& with value "true"), it is indicating that a PSU has directly asked this account access in real-time.

example:

"false"
date_from Query optional string

Conditional: Inclusive minimal imputation date of the transactions in ISO_8601 UTC date format [YYYY-MM-DD]. Transactions having an imputation date equal to this parameter are included in the result.

example:

"2020-08-23T00:00:00.0000000"
date_to Query optional string

Conditional: Exclusive maximal imputation date of the transactions in ISO_8601 UTC date format [YYYY-MM-DD]. Transactions having an imputation date equal to this parameter are not included in the result.

example:

"2020-08-24T00:00:00.0000000"
pagesize Query optional integer

The AISP can provide the pagesize which is the number of records per call. If the original request (given the requested dates) contains more transactions than the number included in the pagesize, the next_page_key will be returned to fetch the other transactions.

example:

"10"
next Query optional string

Conditional: Populate with next_page_key present in the reply from Server if present.

example:

"agSYE1XlpYausCq81CQ"
currency Query optional string

ISO 4217 Alpha 3 currency code.

example:

"EUR"

Response

{
  "transactions": {
    "booked": "[]",
    "next_page_key": "string"
  },
  "_links": "object"
}
Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

()

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Get /accounts/{logical-id}/transactions

Request example

There is no example request provided

Response example

{
  "transactions": {
    "booked": "[]",
    "next_page_key": "string"
  },
  "_links": "object"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}

        
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}

Get list of authorized accounts.

Returns the list of authorized accounts for the PSU, including the encrypted logical-id for each account.


Parameters

Authorization Header required string

The access token. Note that the access token is limited to a given type of request [here AIS] and given IBAN. The token itself should be passed as bearer token in the Authorization header, like: "Bearer 987tghjkiu6trfghjuytrghj".

example:

"Bearer 987tghjkiu6trfghjuytrghj"
Request-ID Header required string

The ID of the request. Must be unique. It has to be a valid UUID in V04 format.

example:

"99391c7e-ad88-49ec-a2ad-99ddcb1f7721"
Accept Header required string

It must be of type application/json including the API version number. [Accept:application/vnd.belfius.api+json; version=1].

example:

"application/vnd.belfius.api+json; version=1"
Accept-Language Header required string

Language. It can include a language in ISO 639-1 format [example: fr]. Note that during redirection, Belfius/Banx screens are only available in French (fr) and Dutch (nl).

example:

"fr"
Client-ID Header required string

The Client ID of a registered AISP, received after the onboarding.

example:

"l7957ffbdbcbf4496a8a406702aacbf539"
psu_involved Query optional boolean

If present (& with value "true"), it is indicating that a PSU has directly asked this account access in real-time.

example:

"false"
pagesize Query optional integer

The AISP can provide the pagesize which is the number of records per call. If the original request (given the requested dates) contains more transactions than the number included in the pagesize, the next_page_key will be returned to fetch the other transactions.

example:

"10"
next Query optional string

Conditional: Populate with next_page_key present in the reply from Server if present.

example:

"agSYE1XlpYausCq81CQ"

Response

{
  "accounts": "[]",
  "next_page_key": "string",
  "_links": {
    "next": {
      "href": "string",
      "templated": "boolean"
    }
  }
}
Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Headers
  • Response-ID: Same as Request-ID, received in request.

Structure of the generic error message object.

example:

{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
  • Fixed-form error tokens mapping to specific errors.

    example:

    string
    error (string)

  • Error specific code, could be used directly by consumer's software.

    example:

    string
    error_code (string)

  • Full description of the error.

    example:

    string
    error_description (string)

Get /accounts

Request example

There is no example request provided

Response example

{
  "accounts": "[]",
  "next_page_key": "string",
  "_links": {
    "next": {
      "href": "string",
      "templated": "boolean"
    }
  }
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}
{
  "error": "string",
  "error_code": "string",
  "error_description": "string"
}