Account API

Preliminary steps

1. Obtain your authorization: All details on this flow can be found in the Flows section of the consent API documentation.
2. Issue your access/refresh tokens: All details on this flow can be found in the Flows section of the consent API documentation.

Retrieving the account list

• GET /accounts

This API allows a TPP to retrieve the list of the account(s) along with their respective identifier (logical-ID) that the PSU has authorized during the redirection flow within the Belfius or Banx environment.

Viewing the details and balance of a PSU's payment account

• GET /accounts/{logical-id}

This API allows a Belfius or Banx PSU to view their account details and its associated balances within a TPP application.

Belfius supports multi-currency accounts. In this case, the returned account balance is always a balance in euro. This balance is associated with either the balance of the euro compartment or the globalized amount in euro of the balance of all compartments (depending on the parameters of the account). A list of each currency compartment with its balance is also provided in the API response.

The steps are as follows:

1. When a PSU would like to view their balance, the TPP calls this API and provides its specified parameters along with the earlier received access token. This communication is secured using eIDAS certificates. If all the provided information is valid, Belfius/Banx responds with the account details and its associated balances.

Retrieving a PSU payment account’s transaction history

• GET /accounts/{logical-id}/transactions

This API allows a Belfius or Banx PSU to view the transaction history of their account within a TPP application.

Belfius supports multi-currency accounts. To retrieve transactions of a specific currency compartment the currency parameters should be filled in. If no currency is given in input, only the euro transactions will be returned.

The steps are as follows:

1. When a PSU would like to view their transactions, the TPP calls this API and provides its specified parameters along with the earlier received access token. This communication is secured using eIDAS certificates. If all the provided details are valid, Belfius/Banx responds with the account’s transactions.

To keep accessing PSU transaction history after 180 days, the PSU will again be required to perform an authentication. The specific flow linked to this case is explained in the below section. Up-to-date account balance will still be available to the PSU without the authentication.

Retrieving the full transaction history

Retrieving transactions older than 90 days can be done at any moment by the TPP. However, two different flows have to be distinguished:

• Retrieving full transaction history immediately after the account enrolment where no additional PSU authentication is required.
  Immediately after the enrolment, the POST /token API called with a scope “AIS” and with “authorization_code” as grant_type will return an “SCA token”. This “SCA token” (valid for a period of 1 hour) should be passed as parameter of the GET /transactions request to retrieve the full transaction history.
• Retrieving transactions older than 90 days at any moment (other than immediately after account enrolment) where an authentication of the PSU is required.

1. When a PSU would like to view their transactions older than 90 days, the TPP calls this API and provides its specified parameters along with the earlier received access token. This communication is secured using eIDAS certificates.
2. In this case the PSU should authenticate once more. The API responds therefore with the appropriate error message and an authentication URL, indicating this to the TPP. The TPP receives a redirect URL to which it needs to add a “state”. This “state” will help the TPP identify the call coming back from the Belfius/Banx when the required authentication steps are finalized.
3. The PSU authenticates himself in the Belfius/Banx environment.
4. The PSU is redirected to the TPP application. To do so, Belfius/Banx will use the callback URL communicated by the TPP when calling the GET /transaction API, and the “state” added in step 2.
5. Now, the TPP retries the original request with the SCA-token received from Belfius/Banx (GET /accounts/{logical-id}/transactions). Belfius/Banx responds successfully by providing the transaction history of the specified payment account.

Renewing the PSU authentication to access transactions

As explained above, the PSU needs to perform a new authentication if

• The PSU wants to continue accessing transactions after their last authentication was done more than 180 days ago
• The TPP wants to retrieve a transaction older than 90 days In this case, the TPP should specify the date using the date_to and date_from parameters.

The steps are as follows:

1. When a PSU would like to view their transactions, the TPP calls this API and provides its specified parameters along with the earlier received access token. This communication is secured using eIDAS certificates.
2. In some cases (explained above), the PSU should authenticate once more. The API responds therefore with the appropriate error message and an authentication URL indicating this to the TPP. The TPP receives a redirect URL to which it needs to add a "state". This "state" will help the TPP identify the call coming back from the Belfius/Banx when the required authentication steps are finalized.
3. The PSU authenticates himself in the Belfius/Banx environment, SCA validity is extended.
4. With validity extended, the PSU is redirected to the TPP application. To do so, Belfius/Banx will use the callback URL communicated by the TPP when calling the GET /transaction API, and the “state” added in step 2.
5. Now, the TPP retries the original request (GET /accounts/{logical-id}/transactions). Belfius/Banx responds successfully by providing the transaction history of the specified payment account.

Note that in case the PSU wants to retrieve transactions older than 90 days, a “SCA token” will be returned after the successful PSU authentication in the Belfius/Banx environment. This “SCA token” (valid for a period of 1 hour) should be passed as parameter of the request. This will allow the TPP to retrieve older transactions.

Retrieving balance and transactions when the PSU is not present

Four unattended calls can be performed on AIS APIs per 24 hours.

In order to do so, the TPP should set the “psu_involved” parameter to false.
Note that if this parameter is empty, Belfius considers that the PSU is not present. This call will therefore be counted by Belfius as unattended.