Get Started

Introduction

Welcome to the Belfius API Portal, your unique platform for building quality applications and solid digital services using Belfius APIs.

Programming interfaces have become a driving force in the development of businesses in all sectors and all activities throughout the world. More than ever businesses need to be able to quickly create added value and innovate all aspects of their organisation (management, processes, solutions, customer experience, etc.)

Belfius is no exception to this rule. We also do everything we can to provide quality services to our customers and partners. This API portal, intended for developers and partners, is a further step in this direction.

In addition to a getting started guide and detailed documentation, we offer a sandbox environment for testing purposes to help you as much as possible in your work.

API Marketplace

The API Marketplace showcases the different APIs available at Belfius along with a link to the detailed documentation for each API. The APIs have been categorized as:

  • Coming soon These are future APIs, for which, for the time being, only documentation exists.
  • Sandboxed These can be used with a Sandbox environment to simulate calls.
  • Live These are APIs for a production environment which can be used directly from your applications.

Getting Access

Access to Live APIs has different security requirements than access to the sandbox. In both cases, you can fill in the contact form to reach out to us for API access.

If you’ve opted to use Live APIs, you will be contacted to provide further information (e.g. certificates, as all our API’s are secured by the MTLS protocol). After this step you will be provided the required credentials for access to our Live APIs.

Sandbox

Once we have given you the credentials, you will be able to fully use our sandbox environment and access the test data of the available APIs. To make it easier for you to get started and to quickly familiarize yourself with the API, this environment doesn’t require certificates or authentication. You still need to fill in the mandatory parameters of the API (values don’t matter) and have valid credentials (which you receive after registering). Please note that the sandboxes return a mocked response and won’t process any actual data.

The sandbox currently only supports the following calls:

  • PSD AIS (Account Information Services) to view an account’s balance and transaction history
  • PSD2 PIS (Payment Initiation Service) to issue a SEPA payment order
  • Sandbox base path: https://sandbox.api.belfius.be:8443/sandbox/psd2

PSD2 Specific APIs

Even though the European PS2 directive only comes into effect in September 2019, Belfius would already like to propose concrete solutions such as this platform. The APIs present here are, for the time being, exclusively related to this directive.

To facilitate their use, Belfius also provides the following APIs:

  • Consent API: GET /consent-uris API to give a ‘Consent’. A Belfius customer on a Third Party Provider (TPP) application authenticates himself in a secure Belfius environment through redirection.
  • Account APIs (AIS): POST /token to obtain an access token. A TPP application requests an access token and exchanges the previously granted authorisation (OAuth2 token API).

Prerequisites for Live PSD2 APIs:

To use Live APIs, you must meet more conditions than for the sandbox. You need to:

  • be recognised as a TPP – or be in the process of being recognised – by the National Bank of Belgium in the context of PSD2
  • have contacted us to request your identification token
  • have provided the certificates required for Mutual TSL authentication or your eIDAS certificates (QWAC et QSeal)
  • have registered the OAuth2 redirect URLs

Please use this token request form.

Account Information Services (AIS) – PSD2 APIs

In the Belfius context, PSD2 AIS APIs provide Belfius customers the possibility to view their account balances and transaction history on a TPP application. PSD2 AIS APIs require the explicit authorisation of the customer, which has been implemented through OAuth2.

The TPP application then can obtain an access token and a refresh token, which will allow it to access the customer’s data.

1) Obtaining authorisation and retrieving tokens

• GET /consent-uris
• POST /token

First an API (GET /consent-uris) starts the authorisation flow, which returns an authorisation code associated with the TPP’s provided redirect URL. This authorisation code can then be used in a second API (POST /token) to obtain an access token and a refresh token, which are required in the AIS PSD2 APIs.

The steps are as follows:

  1. A Belfius customer on a TPP application initiates this authorisation flow by specifying the required information. Once the flow has started, the TPP application calls the /consent-uris API and passes on its specified parameters. This communication is secured using Mutual TLS or eIDAS certificates. Belfius responds with the URL(s) to redirect to customer to the secure Belfius environment (web, tablet or mobile).
  2. The TPP directs the customer to one of these environments using the right URL.
  3. The customer authenticates himself in this environment and grants the TPP access.
  4. The customer is redirected to the TPP application, which receives an authorisation code.
  5. The TPP application then exchanges this authorisation code for an access token, a refresh token and an identifier (logical-id), using the token endpoint. Once the TPP has received the access token, it can then be used in all AIS requests. Note that if an access token expires, the TPP can get a new one by recalling the token endpoint and providing the refresh token as a parameter.

2) Viewing the details and balances of a customer’s current account

• GET /accounts/{logical-id}

This API allows a Belfius customer to view his account details and its associated balances within a TPP application. The prerequisite is that the TPP has a valid access token and an identifier (logical-id).

The steps are as follows:

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

3) Retrieving a customer current account’s transaction history

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

A customer can view the transaction history of his Belfius current account. The prerequisite is that the TPP has both a valid access token and an identifier (logical-id).

The steps are as follows:

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

4) Renewing the authorisation for access to the current account

In accordance with PSD2 specifications, consent has to be renewed every 90 days.

The steps are as follows:

  1. When a customer would like to view his transaction history, the TPP calls this API and provides its specified parameters along with the earlier received access token. In some cases the access authorisation needs to be renewed. The API responds with the appropriate error message, indicating this to the TPP.
  2. The TPP receives a redirect URL to which it needs to add the required ‘state’. The customer then needs to be directed to the Belfius environment.
  3. The customer authenticates himself in the Belfius environment and grants new access to the TPP.
  4. The customer returns to the TPP application.
  5. Now, the TPP retries the original request (GET /accounts/{logical-id}/transactions) by transmitting the access token. Belfius responds successfully by providing the transaction history of the specified current account.

Payment initiation services (PIS) – PSD2 APIs

In the Belfius context, PSD2 PIS APIs provide Belfius customers the possibility to initiate a SEPA payment using their account on a TPP application. As soon as the payment has been made and signed, the TPP application receives an authorisation code if an access token wasn’t provided at the start of the process. This TPP application can then use this authorisation code to get an access token and a refresh token which can then be used for future payment initiations.

1) Initiating and signing a payment

• POST /payments/sepa-credit-transfer

A Belfius customer can initiate a SEPA payment in the TPP application.

The steps are as follows:

  1. When a customer would like to initiate a SEPA payment in a TPP application, the TPP calls this API and provides its specified parameters. In some cases the access authorisation needs to be renewed. The API responds with the appropriate error message.
  2. If the TPP has the required access authorisations, the API responds with either:
    • a message indicating that the payment has been successfully initiated
    • a message indicating the payment initiation requires a signature. In this case, the TPP application also receives a URL in ‘Location header’
  3. The TPP redirects the customer to the URL mentioned in the answer above and adds the required ‘state’. The customer is redirected to the Belfius environment.
  4. 4The client authenticates himself and signs the payment.
  5. Belfius generates an authorisation code.
  6. The customer is again redirected to the TPP application, thus transmitting the authorisation code and the ‘state’ in the redirect URL.

Now the TPP can exchange this authorisation code for an access token and a refresh token using the /token endpoint. This newly acquired access token can then be used for future payments. When a valid access token has been inputted, no authorisation code will be provided in the redirect URL in future calls.