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 dedicated 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. QWAC and QSeal certificates if you wish to use our PSD2 APIs ). 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:

  • PSD2 AIS (Account Information Services) to view an account’s balance and transaction history
  • PSD2 PIS (Payment Initiation Service) to issue or cancel a SEPA payment order
  • PSD2 CAF (Confirmation of the Availability of Funds) to confirm if an amount is available on the account

Testing PSD2 APIs in our sandbox is only accessible to recognised – or be in the process of being recognised- TTP under PSD2 regulation.
To request an access to our sandbox, please use this dedicated form.

Sandbox base path: https://sandbox.api.belfius.be:8443/sandbox/psd2

PSD2 Specific APIs

Currently only APIs linked to the Second Payment Services Directive (PSD2) are available on our live environment.

Belfius PSD2 APIs can be used for all Belfius customers segments (retail, private, wealth, business, corporate, public and social).

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

  • GET /consent-uris. This API allows a Third Party Provider (TPP) to receive the redirect urls while doing a Strong Customer Authentification (SCA) in a Belfius secure environment.
  • POST /token. This API is an authorization API. A TPP application requests an access token and exchanges the previously granted authorization (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 under PSD2 regulation
  • have provided your eIDAS certificates (QWAC et QSeal)
  • have registered the OAuth2 redirect URLs. Note that if you intend to use an application on iOS, the redirect URLs should be universal links.
  • have provided the IP adress(es) from which you will call the Belfius environment.

To request an access to our production PSD2 APIs, please use this dedicated form

Account Information Services (AIS) – PSD2 APIs

In the Belfius context, PSD2 AIS APIs provide Belfius customers the possibility to view their account balance and transaction history on a TPP application. PSD2 AIS APIs require the explicit authorization 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 authorization and retrieving tokens

• GET /consent-uris
• POST /token

First an API (GET /consent-uris) starts the authorization flow, which returns an authorization code associated with the TPP’s provided redirect URL. This authorization 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 authorization 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 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 authorization code.
  5. The TPP application then exchanges this authorization 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 balance 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 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 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 eIDAS certificates. If all the provided details are valid, Belfius responds with the current account’s transactions.

4) Renewing the authorization 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 authorization 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 authorization code if an access token wasn’t provided at the start of the process. This TPP application can then use this authorization 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. One of these parameters in the payment type (value currently accepted are NORMAL and URGENT). Some of these offered services are paying services. You can consult our website to know the exact charges due. In some cases the access authorization needs to be renewed. The API responds with the appropriate error message.
  2. If the TPP has the required access authorizations, 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. The client authenticates himself and signs the payment.
  5. Belfius generates an authorization code.
  6. The customer is again redirected to the TPP application, thus transmitting the authorization code and the ‘state’ in the redirect URL.

Now the TPP can exchange this authorization 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 authorization code will be provided in the redirect URL in future calls.

2) Cancelling a payment

A Belfius customer can cancel an uncompleted SEPA payment transaction initiated earlier in the TPP application.
Please note that in order to cancel the payment, TPP must provide a valid access token as a Bearer token in Authorization header of cancel payment API. This Bearer token is in fact the access token received after calling the token API using the authorization code provided by Belfius at the end of the payment initiation.

The steps are as follows:

  1. When a customer would like to cancel a confirmed payment, 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, and the payment was indeed not confirmed by that time, Belfius will initiate a payment cancellation and respond with the confirmation.

Confirmation on the Availability of Funds (CAF) PSD2 APIs

This endpoint provide the possibility for a TPP to check if enough funds are available at a given payment account (IBAN should be provided).

The steps are as follows:

  1. When a TPP would like to verify the funds availability status, the TPP calls this API and provides its specified parameters along with the earlier received access token for scope CAF. This communication is secured using eIDAS certificates. If all the provided details are valid, Belfius will respond with the fund availability status.