Démarrer

Introduction

Bienvenue sur l’API Portal de Belfius, votre plateforme unique pour le soutien à la création d’applications et de services digitaux de qualité utilisant les APIs de Belfius.

Les interfaces de programmation sont devenues aujourd’hui un vecteur incontournable de développement pour les entreprises de tous les secteurs, de toutes les activités et dans le monde entier. Celles-ci doivent en effet, plus que jamais, pouvoir rapidement créer de la valeur ajoutée et innover dans tous les aspects de leur organisation (gestion, processus, solutions, expérience clients…).

Belfius n'échappe pas à cette règle. Aussi, nous mettons tout en œuvre pour fournir des services de qualité à nos clients et à nos partenaires. Ce portail regroupant nos APIs, et destiné aux développeurs et partenaires, constitue un pas supplémentaire dans cette voie.

En plus d’un guide de démarrage et de documentations détaillées, nous proposons un environnement sandbox à des fins de test pour vous aider à faciliter votre travail au maximum.

API Marketplace

L’API Marketplace présente les différentes APIs disponibles chez Belfius, ainsi qu’un lien vers la documentation détaillée de ces APIs. Chaque API a été classée comme suit:

  • Coming soon: il s’agit d’APIs à venir pour lesquelles il n’existe pour l’instant que de la documentation.
  • Sandbox: il s’agit d’APIs pouvant être utilisées dans un environnement sandbox pour simuler des appels.
  • Live: il s’agit des APIs pour environnement de production pouvant être utilisées directement à partir de vos applications.

Accès

L'accès aux Live API suit des règles de sécurité différentes de l'accès au bac à sable (sandbox). Dans les deux cas, vous pouvez compléter le formulaire de contact dédié pour nous contacter en vue de l'accès API.

Si vous avez choisi d'utiliser les Live API, vous serez contacté pour fournir d'autres informations (p.ex.certificats QWAC et QSeal, si vous souhaitez utiliser nos API PSD2). Après cette étape, vous recevrez les clés nécessaires pour accéder à nos Live API.

Sandbox

Lorsque nous vous aurons fourni les informations d’identification, vous pourrez utiliser pleinement notre environnement sandbox et accéder aux données de test des APIs disponibles. Cet environnement ne nécessite ni certificats ni authentification, et ce, afin de faciliter vos premiers pas et de vous familiariser rapidement avec l’API. Vous devez toutefois toujours fournir les paramètres obligatoires de l’API (les valeurs n’ont pas d’importance ) et une clé API valide (reçue après l’enregistrement). Veuillez noter que les sandbox renvoient une réponse fictive/indéterminée et ne prévoient nullement le traitement des données réelles.

Actuellement, le Sandbox n'accepte que les appels suivants :

  • PSD2 AIS (Account Information Services) pour voir le solde d'un compte et l'historique des transactions
  • PSD2 PIS (Payment Initiation Service) pour émettre ou annuler un ordre de paiement SEPA
  • PSD2 CAF (Confirmation of the Availability of Funds) pour confirmer la présence d'un solde disponible sur le compte

Pour demander l'accès à notre sandbox, veuillez utiliser ce formulaire dédié.

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

API spécifiques à la directive PSD2

Actuellement, seules les API liées à la deuxième directive sur les services de paiement (PSD2) sont disponibles dans notre environnement de production.

Pour faciliter leur utilisation, Belfius fournit en outre les APIs suivantes:

  • GET /consent-uris API pour donner un « consentement »’. Cette API permet à un fournisseur tiers (Third Party Provider - TPP) de recevoir les url de redirection tout en effectuant une Strong Customer Authentification (SCA) dans un environnement Belfius sécurisé.
  • POST /token. Cette API est une API d'autorisation. L'application TPP demande un token d'accès et échange l'autorisation accordée antérieurement (API token OAuth2).

Conditions préalables API Live PSD2

Pour utiliser les Live API, vous devez remplir plus de conditions que pour accéder au sandbox. Vous devez:

  • être reconnu (ou en voie d'être reconnu) comme TPP par la Banque Nationale de Belgique dans le contexte PSD2
  • avoir fourni les certificats eIDAS (QWAC et QSeal)
  • avoir enregistré les URL de redirection OAuth2
  • avoir fourni la ou les adresses IP au départ desquelles vous appellerez l'environnement Belfius

Pour demander l'accès à nos API PSD2 de production, servez-vous de ce formulaire dédié.

Account Information Services (AIS) - API PSD2

Dans le contexte Belfius, les API PSD2 AIS donnent aux clients Belfius la possibilité de consulter le solde de leur compte et l'historique des transactions dans une application TPP. Les API PSD2 AIS exigent l'autorisation explicite du client, ce qui a été implémenté via OAuth2.

1) Obtention des autorisationset retrait des tokens

• GET /consent-uris
• POST /token

D'abord, une API (GET /consent-uris) lance le flux d'autorisation, après quoi celui-ci renvoie un code d'autorisation lié à l'URL de redirection fourni par le TPP. Ce code d'autorisation peut ensuite être utilisé dans une deuxième API (POST /token) pour obtenir un token d'accès et un token d'actualisation (refresh), tous deux requis par les API AIS PSD2.

  1. Un client Belfius utilisant une application TPP initie ce flux d'autorisation en spécifiant les informations requises. Lorsque le flux commence, l'application TPP appelle l'API /consent-uris API avec les paramètres spécifiés. La communication est sécurisée par les certificats Mutual TLS ou eIDAS. Belfius répond en renvoyant le ou les URL pour rediriger le client vers l'environnement Belfius sécurisé (web, tablette ou mobile).
  2. Le TPP utilise l’une de ces URL pour diriger le client vers un de ces environnements.
  3. Le client s’authentifie dans cet environnement et autorise l’accès au TPP.
  4. Le client est redirigé vers l'application TPP, qui reçoit le code d'autorisation.
  5. L'application TPP échange ensuite le code d'autorisation pour un token d'accès, un token d'actualisation et un identifiant (logical-id), à l'aide de la terminaison du token . Une fois que le TPP a reçu le token d'accès, il peut être utilisé dans toutes les requêtes AIS. Notons que si un token d'accès arrive à expiration, le TPP peut en obtenir un nouveau en rappelant la terminaison du token et en passant le token d'actualisation en guise de paramètre.

2) Voir les détails et le solde du compte de paiement d'un client

• GET /accounts/{logical-id}

Cette API permet au client Belfius de consulter les données de son compte à vue et les soldes y afférents au sein d’une application d’un TPP. La condition préalable est que ce dernier dispose d’un access token valide et d’un identifiant (logical-id). Les étapes sont les suivantes:

Quand un client souhaite consulter son solde, le TPP appelle cette API avec les paramètres spécifiés et le token d'accès reçu antérieurement. La communication est sécurisée par les certificats Mutual TLS ou eIDAS. Si toutes les informations sont valables, Belfius renvoie les détails du compte et son solde.

3) Consultation de l’historique des transactions du compte à vue du client

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

Le client peut consulter l’historique des transactions de son compte à vue Belfius. La condition préalable est que le TPP dispose d’un access token valide et d’un identifiant (logical-id). Les étapes sont les suivantes:

  1. Lorsque que le client souhaite consulter ses transactions, le TPP appelle cette API et transmet les paramètres attendus selon ses spécifications et l’access token reçu antérieurement. Cette communication est sécurisée par Mutual TLS ou par l’usage de certificats eIDAS. Si toutes les informations fournies sont valides, Belfius répond en fournissant les transactions du compte à vue.

4) Renouvellement de l’autorisation d’accès au compte de paiement.

Conformément aux spécifications PSD2, l’autorisation d’accès peut être renouvelée tous les 90 jours. Les étapes sont les suivantes:

  1. Quand un client souhaite consulter l'historique de ses transactions, le TPP appelle cette API avec les paramètres spécifiés et le token d'accès reçu antérieurement. Dans certains cas, l'autorisation d'accès doit être renouvelée. L'API renvoie le message d'erreur correspondant, à l'intention du TPP.
  2. Le TPP reçoit une url de redirection à laquelle il devra ajouter le «state» requis. Le client doit ensuite être redirigé vers l’environnement Belfius.
  3. Le client s’authentifie dans l’environnement Belfius et accorde un nouvel accès au TPP.
  4. Le client revient à nouveau vers l’application du TPP.
  5. À présent, le TPP réessaie la requête originale (GET /accounts/{logical-id}/transactions), en transmettant l’access token. Belfius répond avec succès en fournissant l’historique des transactions du compte à vue indiqué.

Payment initiation services (PIS) - PSD2 APIs

Dans le contexte Belfius, les API PSD2 PIS donnent aux clients Belfius la possibilité d'émettre un paiement SEPA au départ de leur compte, dans une application TPP. Dès que le paiement a été effectué et signé, l'application TPP reçoit un code d'autorisation si le token d'accès n'a pas été transmis au début du processus. L'application TPP peut ensuite se servir du code d'autorisation pour obtenir un token d'accès et un token d'actualisation en vue des futurs paiements.

1) Initiation de paiement et signature

• POST /payments/sepa-credit-transfer

Un client Belfius peut initier un paiement SEPA sur l’application TPP. Les étapes sont les suivantes:

  1. Si un client souhaite émettre un paiement SEPA à partir d'une application TPP, le TPP appelle cette API avec les paramètres spécifiés. Dans certains cas, l'autorisation d'accès doit être renouvelée. L'API renvoie le message d'erreur correspondant.
  2. Si le TPP dispose de l'autorisation d'accès, l'API renvoie:
    • un message disant que le paiement a été effectué avec succès,
      ou
    • un message disant que le paiement nécessite une signature. Dans ce cas, l'application TPP reçoit aussi un URL dans ‘Location header’.
  3. Le TPP redirige le client vers l’URL mentionnée dans la réponse ci-dessus et ajoute le «state» requis. Le client est redirigé vers l’environnement Belfius.
  4. Le client s'authentifie et signe le paiement.
  5. Belfius génère un code d’autorisation.
  6. Le client est à nouveau redirigé vers l'application TPP, transmettant le code d'autorisation ainsi que l' « état » dans l'URL de redirection.

À ce stade, le TPP peut échanger le code d'autorisation contre un token d'accès et un token d'actualisation à l'aide de la terminaison du token. Ce token d'accès nouvellement obtenu pourra servir aux futurs paiements. Si un token accès valable a été soumis, le code d'autorisation ne sera pas fourni dans l'URL de redirection lors des futurs appels.

2) Annuler un paiement

Un client Belfius peut annuler un virement SEPA incomplet précédemment créé dans l'application du TPP. Veuillez noter que pour annuler le virement, le TPP doit fournir un access token valide comme Bearer token dans l'en-tête d'autorisation de l'API Annulation de virement. Ce Bearer token est en fait le access token reçu après l'appel du token API en utilisant le code d'autorisation fourni par Belfius à l'issue de la création du virement.

Les étapes sont les suivantes:

  1. Lorsqu'un client souhaite annuler un virement confirmé, le TPP appelle cette API et fournit ses paramètres spécifiés ainsi que l’access token précédemment reçu. Cette communication est sécurisée par des certificats eIDAS. Si tous les détails fournis sont valables et si le paiement n'a pas été confirmé à ce moment-là, Belfius procédera à une annulation du virement et confirmera l'opération.

API Confirmation on the Availability of Funds (CAF) PSD2

Ce paramètre permet à un TPP de vérifier s'il y a suffisamment de fonds disponibles sur un compte bancaire donné (il faut fournir l'IBAN).

Les étapes sont les suivantes:

  1. Lorsqu'un TPP souhaite vérifier la disponibilité des fonds, il appelle cette API et fournit ses paramètres spécifiés ainsi que l’access token reçu précédemment pour le cadre CAF. Cette communication est sécurisée par des certificats eIDAS. Si tous les détails fournis sont valables, Belfius communiquera la disponibilité des fonds.