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

Les exigences de sécurité pour accéder aux APIs Live et aux sandbox ne sont pas les mêmes. Dans les deux cas, vous pouvez remplir le formulaire de contact pour vous mettre en rapport avec nous en vue d’accéder à nos APIs.

Si vous avez choisi d’utiliser aussi des APIs Live, vous serez contacté afin de nous fournir des informations supplémentaires (par exemple des certificats puisque toutes nos APIs sont sécurisées par le protocole MTLS). Dès l’achèvement de cette étape, vous recevrez les informations d’identification requises pour vous permettre d’accéder à nos APIs Live.

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.

La sandbox prend actuellement les appels suivants en charge:

  • AIS (Account information Services) PSD2 pour consulter le solde et l’historique des transactions sur un compte
  • PIS (Payment initiation services) PSD2 pour émettre un ordre de paiement SEPA
  • Sandbox base path: https://sandbox.api.belfius.be:8443/sandbox/psd2

API spécifiques à la directive PSD2

Malgré le fait que la directive européenne PSD2 ne rentre en application qu’en septembre 2019, Belfius a la volonté de déjà proposer des solutions concrètes, comme cette plateforme. Les APIs présentes ici sont, pour le moment exclusivement liées à cette directive.

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

  • «Consent»: le client Belfius utilisant l’application d’un fournisseur tiers (Third Party Provider ou TPP) s’authentifie dans un environnement Belfius sécurisé au moyen d’une redirection. Obtention d’un access token: l’application d’un TPP demande un access token et échange l’autorisation accordée antérieurement (API de token OAuth2).

Conditions préalables pour les API PSD2 Live

Contrairement à la sandbox, pour utiliser ces APIs Live, vous devez remplir les conditions suivantes:

  • être reconnu comme TPP – ou en cours de reconnaissance – par la Banque Nationale de Belgique dans le cadre de PSD2
  • nous avoir contacté pour demander votre token d’identification
  • avoir fourni les certificats requis pour l’authentification Mutual TLS ou vos certificats eIDAS (QWAC, et QSeal)
  • avoir enregistré les URL de redirection OAuth2

Veuillez utiliser ce formulaire de demande de token.

Account Information Services (AIS) - PSD2 APIs

Pour Belfius, les APIs AIS PSD2 offrent au client la possibilité de consulter le solde de ses comptes à vue et l’historique des transactions via l’application d’un TPP. Les APIs AIS PSD2 nécessitent l’autorisation explicite du client, ce qui a été mis en œuvre à l’aide de l’autorisation OAuth2. L’application du TPP peut ensuite obtenir un access token et un refresh token. Ce qui permettra au TPP d’accéder aux données du client.

1) Obtention de l’autorisation et récupération des tokens

• GET /consent-uris
• POST /token

Tout d’abord, une API (GET /consent-uris) lance le flux d’autorisation, qui renvoie un code associé à l’URL de redirection fournie par le TPP. Ce code d’autorisation peut ensuite être utilisé dans une deuxième API (POST /token) pour obtenir un access token et un refresh token requis dans les APIs AIS PSD2. Les étapes sont les suivantes:

  1. Un client Belfius amorce ce processus d’autorisation sur une application fournie par un TPP en précisant les informations requises. Une fois le flux amorcé, l’application du TPP appelle l’API/consent-uris et transmet les paramètres attendus selon les spécifications de cette API. Notez que cette communication est sécurisée par une authentification Mutual TLS ou par l’usage de certificats eIDAS. Belfius fournit en retour la ou les url permettant de rediriger le client vers un environnement sécurisé Belfius (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 revient vers l’application du TPP, celui-ci reçoit un code d’autorisation.
  5. En utilisant le token endpoint, l’application du TPP échange alors ce code d’autorisation contre un access token, un refresh token et un identifiant (logical-id). Dès que le TPP a reçu l’access token, celui-ci peut ensuite être utilisé dans toutes les requêtes AIS. Notez qu’en cas d’expiration d’un access token, le TPP peut en obtenir un nouveau en rappelant le token endpoint avec le refresh token en paramètre.

2) Consultation des données du compte à vue du client et des soldes y afférents

• 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:

Lorsque que le client souhaite consulter ses soldes, 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 données du compte à vue et les soldes y afférents.

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 à vue.

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. Lorsque que le client souhaite consulter l’historique de 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. Dans certains cas, l’autorisation d’accès doit être renouvelée. L’API répondra par un message d’erreur approprié qui indique au TPP que l’autorisation doit être renouvelée.
  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 de Belfius, les APIs PIS PSD2 offrent au client Belfius la possibilité d’émettre un ordre de paiement SEPA grâce à son compte sur l’application d’un TPP. Une fois le paiement effectué et signé, l’application du TPP reçoit un code d’autorisation si aucun access token n’a été fourni au début de la procédure. Cette application du TPP peut ensuite utiliser ce code d’autorisation pour obtenir un access token & un refresh token qui pourront être utilisés lors de futures initiations de paiement.

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. Lorsque que le client souhaite initier un paiement SEPA à partir de l’application d’un TPP. Celui-ci appelle cette API et transmet les paramètres attendus selon ses spécifications. Dans certains cas, le renouvellement de l’autorisation d’accès peut être exigée. L’API répondra par un message d’erreur approprié.
  2. Si le TPP a les autorisations d’accès requises, l’API répondra soit:
    • par un message qui indique que l’initiation du paiement est réussie
    • par un message qui indique que l’initiation du paiement requiert une signature. Dans le second cas, l’application du TPP reçoit également une 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 redirigé à nouveau vers l’application du TPP, transmettant ainsi le code d’autorisation et le «state» dans l’URL de redirection.

À présent, le TPP peut échanger ce code d’autorisation contre un access token & refresh token en utilisant l’token endpoint. L’access token nouvellement acquis peut ensuite être utilisé pour des paiements ultérieurs. Le fait d’avoir un access token valide en entrée ne fournira pas d’autre code d’autorisation dans l’URL de redirection lors de futurs appels.