Aan de slag

Introductie

Welkom op het API-portaal van Belfius, uw platform voor het maken van performante diensten en applicaties met behulp van Belfius-API's.

Bedrijven over heel de wereld en in alle sectoren kunnen niet langer om programmeerinterfaces heen, willen ze zich blijven ontwikkelen. Ze moeten meer dan ooit snel toegevoegde waarde kunnen creëren en elk aspect van hun organisatie voortdurend innoveren (beheer, proces, oplossingen, klantervaring…).

Dat geldt ook voor Belfius. Ook wij doen er alles aan om onze partners en klanten uitstekende diensten te bieden. Dit API-portaal voor ontwikkelaars en partners is daar een extra stap in.

Om u zoveel mogelijk te helpen krijgt u naast deze Aan de slag-gids en gedetailleerde documentatie ook toegang tot een sandboxomgeving voor tests.

API Marketplace

In de API Marketplace ontdekt u de verschillende Belfius-API’s samen met een link naar de gedetailleerde documentatie van elke API. De API’s vallen onder de volgende categorieën:

  • Coming soon dit zijn API’s waarvoor voorlopig alleen documentatie bestaat
  • Sandboxed met deze API’s kan u oproepen simuleren in een sandboxomgeving
  • Live dit zijn API’s voor de productieomgeving. U kan ze rechtstreeks vanuit uw applicaties gebruiken

Toegang

Voor toegang tot Live API's gelden andere veiligheidseisen dan voor toegang tot sandbox API’s. U vult in beide gevallen het contactformulier in om uw toegang aan te vragen.

Wil u toegang tot Live API's, dan contacteren we u voor meer informatie (zoals certificaten, aangezien al onze API's MTLS-beschermd zijn). Daarna krijgt u de nodige credentials.

Sandbox

Zodra u van ons uw credentials krijgt, hebt u volledige toegang tot onze sandboxomgeving en de testgegevens van de beschikbare API’s. U hebt geen certificaten of authenticatie nodig. Zo kan u snel met de API vertrouwd raken. U moet wel nog altijd de verplichte parameters van de API invullen (de waarden doen er niet toe) en over de geldige credentials beschikken (die u na registratie krijgt). De sandbox geeft mocked data als antwoorden en verwerken nooit echte gegevens.

De sandbox ondersteunt momenteel de volgende oproepen:

  • AIS (Account information services) PSD2 om het saldo en de verrichtingshistoriek van een rekening te zien
  • PIS (Payment initiation services) PSD2 om opdracht te geven tot een SEPA-betaling
  • Sandbox base path: https://sandbox.api.belfius.be:8443/sandbox/psd2

Specifieke API’s voor de PSD2-richtlijn

De Europese PSD2-richtlijn treedt pas in september 2019 in werking. Toch wil Belfius graag nu al met concrete oplossingen komen, zoals dit platform. De hieronder vermelde API’s hebben momenteel uitsluitend op deze richtlijn betrekking.

Voor hun goede werking biedt Belfius ook de volgende API’s aan:

  • Consent API: GET /consent-uris API voor het geven van een ‘Consent’. Een Belfius-klant gebruikt een applicatie van een externe leverancier (Third Party Provider of TPP) en authenticeert zich via een omleiding in een beveiligde Belfius-omgeving.
  • Account API’s (AIS): POST /token om een access token verkrijgen. De applicatie van de TPP vraagt een access token en ruilt daarvoor de eerder verkregen autorisatie in (API van de OAuth2-token).

Voorwaarden voor PSD2 Live API's

Om Live API’s te gebruiken moet u aan meer voorwaarden voldoen dan voor de sandbox:

  • u bent erkend als TPP – of bent in het proces om als TPP erkend te worden – door de Nationale Bank van België, in het kader van PSD2
  • u contacteerde ons om uw identificatietoken aan te vragen
  • u bezorgde ons de certificaten die nodig zijn voor Mutual TLS-authenticatie of uw eIDAS-certificaten (QWAC en QSeaL)
  • u hebt de OAuth2 redirect URL’s geregistreerd

U kan uw token met dit formulier aanvragen.

Account Information Services (AIS) - PSD2 API's

Met de AIS PSD2 API’s geeft Belfius klanten toegang tot hun rekeningsaldi en verrichtingshistoriek via de applicatie van een TPP. AIS PSD2 API's vereisen de expliciete toestemming van de klant, die via OAuth2 gegeven wordt. De TPP-applicatie kan daarna een access token en refresh token krijgen om toegang tot de gegevens van de klant te bekomen.

1) Autorisatie krijgen en tokens ophalen

• GET /consent-uris
• POST /token

Eerst start een API (GET /consent-uris) de autorisatiestroom, die een code terugstuurt die gekoppeld is aan de redirect URL die de TPP verstrekt. Deze autorisatiecode kan vervolgens gebruikt worden in een tweede API (POST /token) om een access token en een refresh token te verkrijgen, die in AIS API’s vereist zijn.

Dit zijn de stappen:

  1. Een Belfius-klant start dit autorisatieproces op in een applicatie van een TPP en specifieert de nodige gegevens. Zodra de flow gestart is, roept de TPP-applicatie de /consent-uris-API op en stuurt hij de juiste parameters door volgens de specificaties van die API. Merk op dat deze communicatie met behulp van Mutual TLS of eIDAS-certificaten wordt beveiligd. Belfius antwoordt met de URL('s) die de klant doorverwijst/doorverwijzen naar een beveiligde Belfius-omgeving (web, tablet of mobiel).
  2. De TPP leidt de klant naar een van die omgevingen met de juiste URL.
  3. De klant authenticeert zich in die omgeving en autoriseert toegang tot de TPP.
  4. De klant wordt teruggeleid naar de TPP-applicatie, die een autorisatiecode krijgt.
  5. De TPP-applicatie gebruikt dan de endpoint ‘token’ om die autorisatiecode tegen een access token, een refresh token en een identifier (logical-id) om te ruilen. Zodra de TPP de access token heeft, kan hij die voor alle AIS-verzoeken gebruiken. Merk op dat wanneer de access token vervalt, de TPP een nieuwe kan bekomen door de endpoint ‘token’ op te roepen met de refresh token als parameter.

2) De gegevens en saldi van de zichtrekening van de klant raadplegen

• GET /accounts/{logical-id}

Met deze API kan de Belfius-klant binnen een TPP-applicatie de gegevens en saldi van zijn zichtrekening raadplegen. Voorwaarde is dat de TPP een geldige access token en een identifier (logical-id) heeft.

Dit zijn de stappen:

  1. Wil de klant zijn saldi raadplegen, dan roept de TPP deze API op en stuurt hij de juiste parameters door volgens de specificaties van de API, samen met de eerder ontvangen access token. Deze communicatie wordt beveiligd met behulp van Mutual TLS of eIDAS-certificaten. Als alle geleverde informatie geldig is, dan antwoordt Belfius met de gegevens en saldi van de zichtrekening.

3) De verrichtingshistoriek van de zichtrekening van de klant raadplegen

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

De klant kan binnen een TPP-applicatie de verrichtingshistoriek van zijn Belfius-zichtrekening raadplegen. Voorwaarde is dat de TPP een geldige access token en een identifier (logical-id) heeft.

Dit zijn de stappen:

  1. Wil de klant zijn verrichtingen raadplegen, dan roept de TPP deze API op en stuurt hij de juiste parameters door volgens de specificaties van de API, samen met de eerder ontvangen access token. Deze communicatie wordt beveiligd met behulp van Mutual TLS of eIDAS-certificaten. Als alle geleverde informatie geldig is, dan antwoordt Belfius met de verrichtingen van de zichtrekening.

4) De toestemming voor de toegang tot de zichtrekening vernieuwen.

De PSD2-richtlijn legt op dat de toestemming om de 90 dagen moet worden vernieuwd.

Dit zijn de stappen:

  1. Wil de klant zijn verrichtingshistoriek raadplegen, dan roept de TPP deze API op en stuurt hij de juiste parameters door volgens de specificaties van de API, samen met de eerder ontvangen access token. Soms moet de autorisatiecode vernieuwd worden. De API laat dit dan met de gepaste foutmelding aan de TPP weten.
  2. De TPP ontvangt een redirect URL waaraan hij de vereiste ‘state’ moet toevoegen. De klant moet vervolgens naar de Belfius-omgeving worden doorverwezen.
  3. De klant authenticeert zich in de Belfius-omgeving en verleent opnieuw toegang aan de TPP.
  4. De klant keert terug naar de TPP-applicatie.
  5. Tenslotte probeert de TPP het oorspronkelijke verzoek opnieuw (GET /accounts/{logical-id}/transactions) en stuurt hij ook de access token door. Belfius antwoordt met de verrichtingshistoriek van de aangegeven zichtrekening.

Payment initiation services (PIS) - PSD2 API’s:

In de Belfius-context kan een Belfius-klant met PSD2 PIS API’s SEPA-betalingen starten dankzij zijn account op de TPP-applicatie. Zodra de betaling uitgevoerd en ondertekend is, krijgt de TPP-app ook een autorisatiecode als er in het begin geen access token werd gestuurd. De TPP-applicatie kan deze autorisatiecode daarna gebruiken om een access token en refresh token te verkrijgen. Die kunnen dan worden gebruikt om in de toekomst betalingen mee te initiëren.

1) Een betaling initiëren en ondertekenen

• POST /payments/sepa-credit-transfer

Een Belfius-klant kan via een TPP-applicatie een SEPA-betaling initiëren.

Dit zijn de stappen:

  1. De klant wil vanaf een TPP-applicatie een SEPA-betaling initiëren. De TPP-applicatie roept deze API op en stuurt de juiste parameters door volgens de specificaties van de API. Soms moet de autorisatiecode vernieuwd worden. De API laat dit dan met de gepaste foutmelding aan de TPP weten.
  2. Als de TPP de nodige autorisaties heeft, antwoordt de API:
    • ofwel met de boodschap dat de betaling geslaagd is
    • ofwel met de boodschap dat de initiatie van de betaling moet getekend worden. Dan krijgt de TPP-applicatie ook een URL in ‘Location header’.
  3. De TPP stuurt de klant naar deze URL en voegt de nodige ‘state’ toe. De klant wordt naar de Belfius-omgeving geleid.
  4. De klant authenticeert zich en tekent de betaling.
  5. Belfius genereert een autorisatiecode.
  6. De klant wordt opnieuw naar de TPP-applicatie geleid en de autorisatiecode en de ‘state’ worden in de redirect URL verstuurd.

Nu kan de TPP deze autorisatiecode met de endpoint ‘token’ omruilen tegen een access token en refresh token. Deze access token kan daarna worden gebruikt voor toekomstige betalingen. Omdat de TPP nu een geldige access token heeft, worden er tijdens toekomstige oproepen geen andere autorisatiecodes in de redirect URL meegegeven.