Consent API

Obtain the tokens necessary to call the PSD2 APIs

Preliminary note

•Obtaining authorization and issuing access/refresh tokens are mandatory preliminary steps to use the AIS and CAF APIs.
•The scope of the authorization (AIS or CAF) should be indicated as a parameter when calling GET /consent-uri API.
•Issuing access/refresh tokens is necessary for payment initiation cancellation and retrieving payment initiation details. Once issued the tokens can also be used when initiating or cancelling another payment.

Note that Belfius/Banx only supports one access/refresh token per scope. If the tokens are refreshed, the previous tokens will not be usable anymore.

Obtaining PSU authentication and retrieving tokens for AIS

• GET /consent-uris
• POST /token

The API GET /consent-uris starts the authentication flow, it will return a redirection URL. This URL should be used to perform the PSU authentication. If the PSU authentication is successful, the call-back URL will return an authorization code. 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.

Only version 4 of the GET /consent-uris API and version 3 of the POST /token API should be used for scope AIS. No account is required in input of the GET /consent-uris API and no logical-ID will be returned by the POST /token API. To retrieve the IBAN and logical-ID of the account(s) authorized by the PSU, the GET /accounts API should be called as explained in the flow section of the AIS API.

Note when the POST /token is called with "authorization_code" as grant_type, an “SCA token” will also be returned. This token can be used to retrieve the full transaction history as explained in the Flows section of the AIS API.

The steps are as follows:

  1. A Belfius or Banx customer on a TPP application initiates this authorization flow. Once the flow has started, the TPP calls the GET /consent-uris API and passes the scope “AIS” and the other parameters. This communication is secured using eIDAS certificates. Belfius/Banx responds with the authorization URL(s) to redirect the PSU to the secure Belfius or Banx environment (web, tablet or mobile).
  2. The TPP directs the PSU to one of these environments using the authorization URL to which it needs to add a "state". This “state” will help the TPP identify the call coming back from Belfius/Banx when the required authentication steps are finalized.
  3. The PSU authenticates themselves in this environment. The PSU will have the possibility to choose from a list which payment account(s) they want to authorize in the TPP application.
  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 consent-uris and the “state” added in step 2. Belfius/Banx will answer with an authorization code or an error in case of failure.
  5. The TPP then exchanges this authorization code for an access token and a refresh token using the POST /token API with “authorization_code” as grant_type. Once the TPP has received the access token, it can then be used in all AIS requests. The TPP can call the GET /accounts API to retrieve a list of the authorized IBAN account numbers and the corresponding logical-IDs.

Obtaining PSU authentication and retrieving tokens for CAF

• GET /consent-uris
• POST /token

The API GET /consent-uris starts the authentication flow, it will return a redirection URL. This URL should be used to perform the PSU authentication. If the PSU authentication is successful, the callback URL will return an authorization code. This authorization code can then be used in a second API POST /token to obtain an access token, a logical-ID and a refresh token, which are required in the CAF PSD2 APIs.

Note that version 4 of the GET /consent-uris and version 3 of the POST /token API cannot be used for CAF. This means that an account is always necessary in input of the GET /consent-uris API.

The steps are as follows:

  1. A Belfius or Banx customer on a TPP application initiates this authorization flow. Once the flow has started, the TPP calls the GET /consent-uris API and passes an IBAN account number, the scope “CAF” and the other parameters. This communication is secured using eIDAS certificates. Belfius/Banx responds with the URL(s) to redirect the PSU to the secure Belfius or Banx environment (web, tablet or mobile).
  2. The TPP directs the PSU to one of these environments using the authorization URL to which it needs to add a "state". This "state" will help the TPP identify the call coming back from Belfius/Banx when the required authentication steps are finalized.
  3. The PSU authenticates themselves in this 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 consent-uris and the “state” added in step 2. Belfius/Banx will answer with an authorization code or an error in case of failure.
  5. The TPP then exchanges this authorization code for an access token, a refresh token and an identifier (logical-ID), using the POST /token API with “authorization_code” as grant_type. Once the TPP has received the access token and logical-ID, they can then be used in all CAF requests.

Retrieving tokens for the PIS flow

• POST /token

To cancel a payment or retrieve payment details, an access token is required.

If the payment initiation was done without using a token, the TPP will receive an authorization code in the callback URL. This code can be used to retrieve access and refresh tokens. This is done by calling the POST /token API using the authorization code received and with “authorization_code” as grant_type. The API will return access and refresh tokens.

Refreshing tokens

• POST /token

After expiration of the access token (valid for a period of 1 hour), the TPP can refresh the tokens received through the POST /token API.

This is done by recalling the POST /token API with the valid refresh token and “refresh_token” as grant_type.

The API will return new access and refresh tokens. The logical-ID communicated before in case of CAF flow is unchanged by this request.

General conditions  | Terms of Use