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

De toegang tot Live API’s heeft andere veiligheidseisen dan de toegang tot de sandbox. In beide gevallen kan u het speciale contactformulier invullen om contact met ons op te nemen voor uw API-toegang.

Als u ervoor hebt gekozen om gebruik te maken van Live API’s, zal u worden gecontacteerd om meer informatie te verstrekken (o.a. QWAC- en QSeal-certificaten, als u onze PSD2 API’s wil gebruiken). Na deze stap krijgt u de vereiste legitimatie om toegang te krijgen tot onze Live API’s.

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:

  • PSD2 AIS (Account Information Services) om het saldo en de transactiehistoriek van een rekening te bekijken
  • PSD2 PIS (Payment Initiation Service) om een SEPA-betaalopdracht aan te maken of te annuleren
  • PSD2 CAF (Confirmation of the Availability of Funds) om te bevestigen of er een bedrag beschikbaar is op de rekening

Het testen van PSD2 API‘s in onze sandbox is alleen toegankelijk voor een erkende, of in behandeling zijnde om te worden erkend, TTP onder de PSD2-regeling.

Om toegang te vragen tot onze sandbox, dient u dit speciale formulier te gebruiken. Het Speciale Formulier moet worden gekoppeld aan het sandbox-formulier

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

Specifieke API’s voor de PSD2-richtlijn

Momenteel zijn alleen API’s, gekoppeld aan de Second Payment Services Directive (PSD2), beschikbaar in onze live omgeving.

Om het gebruik ervan te vergemakkelijken voorziet Belfius ook de volgende API’s:

  • GET /consent-uris. Deze API biedt een Third Party Provider (TPP) de mogelijkheid om de redirect URL’s te ontvangen bij het uitvoeren van een Strong Customer Authentification (SCA) in een beveiligde Belfius-omgeving.
  • POST /token. Deze API is een autorisatie-API. Een TPP-toepassing verzoekt om een access token en ruilt de eerder verleende autorisatie in (OAuth2 token API).

Basisvoorwaarden voor Live PSD2 API’s

Om Live API’s te gebruiken, moet u voldoen aan meer voorwaarden dan voor het gebruik van de sandbox. U moet:

  • worden erkend als een TPP onder de PSD2-regeling
  • uw eIDAS-certificaten hebben bezorgd (QWAC en QSeal)
  • de OAuth2 redirect URL’s hebben geregistreerd. Houd er rekening mee dat de doorverwijzings-URL‘s universele links moeten zijn als u van plan bent om een applicatie op iOS te gebruiken.
  • het (de) IP-adres(sen) hebben bezorgd vanwaar u de Belfius-omgeving zal oproepen

Om toegang aan te vragen tot onze PSD2 productie-API’s, dient u gebruik te maken van dit speciale formulier. Het Speciale Formulier moet worden gekoppeld aan het productieformulier.

Account Information Services (AIS) - PSD2 API's

In de Belfius-context bieden PSD2 AIS API’s de klanten van Belfius de mogelijkheid om het saldo en de transactiehistoriek van hun rekening te bekijken via een TPP-toepassing. PSD2 AIS API’s vereisen de uitdrukkelijke autorisatie van de klant, wat werd geïmplementeerd door middel van OAuth2.

1) Het verkrijgen van autorisatie en het oproepen van tokens

• GET /consent-uris
• POST /token

Eerst start een API (GET /consent-uris) de autorisatie-flow, die uitmondt in een autorisatie-code, gekoppeld aan de door de TPP voorziene redirect URL. Deze autorisatie-code kan dan worden gebruikt in een tweede API (POST /token) om een access token en een refresh token te verkrijgen, die nodig zijn voor de AIS PSD2 API’s.

Dit zijn de stappen:

  1. Een klant van Belfius in een TPP-toepassing start de autorisatie-flow op door de vereiste informatie te specifiëren. Zodra de flow is gestart, roept de TPP-toepassing de /consent-uris API op en geeft ze haar gespecifieerde parameters door. Deze communicatie wordt beveiligd door middel van eIDAS-certificaten. Belfius antwoordt met de URL(‘s) om de klant om te leiden naar de beveiligde Belfius-omgeving (web, tablet of smartphone).
  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 omgeleid naar de TPP-toepassing, die een autorisatie-code ontvangt.
  5. De TPP-toepassing ruilt deze autorisatie-code vervolgens in voor een access token, een refresh token en een identifier (logical-id), met behulp van het token endpoint. Zodra de TPP het access token heeft ontvangen, kan dit worden gebruikt in het kader van alle AIS-verzoeken. Noteer dat de TPP, wanneer een access token vervalt, een nieuw token kan krijgen door het token endpoint opnieuw op te roepen en het refresh token op te geven als parameter.

2) Het bekijken van details en het saldo van de rekening-courant van een klant

• GET /accounts/{logical-id}

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

Dit zijn de stappen:

  1. Wanneer een klant zijn saldo wil bekijken, roept de TPP deze API op en verstrekt hij de gespecificeerde parameters samen met het eerder ontvangen access token. Deze communicatie wordt beveiligd door middel van eIDAS-certificaten. Als alle verstrekte informatie geldig is, antwoordt Belfius met de rekeningdetails en het bijhorende saldo

3) De verrichtingshistoriek van de betaalrekening van de klant raadplegen

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

De klant kan binnen een TPP-applicatie de verrichtingshistoriek van zijn Belfius-betaalrekening 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 is beveiligd met eIDAS-certificaten. Als alle geleverde informatie geldig is, dan antwoordt Belfius met de verrichtingen van de betaalrekening .

4) Het vernieuwen van de toestemming voor de toegang tot de betaalrekening.

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

Dit zijn de stappen:

  1. Wanneer een klant zijn transactiehistoriek wil bekijken, roept de TPP deze API op en verstrekt hij de gespecifieerde parameters samen met het eerder ontvangen access token. In bepaalde gevallen moet de toegangsautorisatie worden vernieuwd. De API antwoordt met de gepaste foutmelding en meldt dit zo aan de TPP.
  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 betaalrekening.

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

In de Belfius-context bieden PSD2 PIS API’s de klanten van Belfius de mogelijkheid om een SEPA-betaling op te starten met gebruikmaking van hun rekening in een TPP-toepassing. Zodra de betaling is gedaan en ondertekend, ontvangt de TPP-toepassing een autorisatie-code als er geen access token werd gegeven bij de aanvang van het proces. Deze TPP-toepassing kan die autorisatie-code dan gebruiken om een access token en een refresh token te verkrijgen. Deze kunnen dan weer worden gebruikt wanneer er later betalingen worden opgestart.

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. Wanneer een klant een SEPA-betaling wil opstarten in een TPP-toepassing, roept de TPP deze API op en verstrekt hij de gespecifieerde parameters. Een van deze parameters is het betalingstype (momenteel aanvaarde waarden zijn NORMAL en URGENT). Sommige van deze aangeboden diensten zijn betalend. U kunt onze website raadplegen om de exacte kosten te kennen. In bepaalde gevallen moet de toegangsautorisatie worden vernieuwd. De API antwoordt met de gepaste foutmelding.
  2. Als de TPP de vereiste toegangsautorisatie heeft, antwoordt de API ofwel met:
    • een melding die aangeeft dat de betaling met succes werd opgestart
    • ofwel met een melding die aangeeft dat het opstarten van de betaling een handtekening vereist. In dit geval ontvangt de TPP-toepassing 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 zichzelf en ondertekent de betaling.
  5. Belfius genereert een autorisatie-code.
  6. De klant wordt weer omgeleid naar de TPP-toepassing, waarbij de autorisatie-code wordt doorgestuurd alsook de ‘state’ in de redirect URL.

Nu kan de TPP deze autorisatie-code inruilen voor een access token en een refresh token met gebruikmaking van het /token endpoint. Dit nieuw verworven access token kan dan worden gebruikt voor latere betalingen. Wanneer er een geldig access token werd ingegeven, zal er in het kader van latere oproepen geen autorisatie-code worden verstrekt in de redirect URL.

2) Een betaling annuleren

Een Belfius-klant kan een onvoltooide SEPA-betalingstransactie, die eerder in de TPP-applicatie is geactiveerd, nog annuleren. Houd er rekening mee dat TPP een geldige access token als Bearer-token in de autorisatieheader van de API voor betalingsannulering moet opgeven om de betaling te annuleren. Deze Bearer-token is eigenlijk de access token die wordt ontvangen nadat de token-API wordt opgeroepen door middel van de autorisatiecode die aan het einde van de betalingsactivering door Belfius wordt bezorgd.

Dit zijn de stappen:

  1. Wanneer een klant een bevestigde betaling wil annuleren, roept TPP deze API op en worden de opgegeven parameters samen met de eerder ontvangen access token bezorgd. Deze communicatie is beveiligd met eIDAS-certificaten. Als alle verstrekte gegevens geldig zijn en de betaling op dat moment inderdaad nog niet is bevestigd, zal Belfius een betalingsannulering activeren en met de bevestiging antwoorden.

Confirmation on the Availability of Funds (CAF) PSD2 APIs

Dit eindpunt biedt de mogelijkheid voor een TPP om te controleren of er op een bepaalde betaalrekening voldoende middelen beschikbaar zijn (IBAN moet worden verstrekt).

The steps are as follows:

  1. Wanneer een TPP de status van de beschikbaarheid van de middelen wil controleren, roept de TPP deze API op en worden de opgegeven parameters samen met de eerder ontvangen access token voor het bereik CAF bezorgd. Deze communicatie is beveiligd met eIDAS-certificaten. Als alle verstrekte gegevens geldig zijn, zal Belfius met de status van de beschikbaarheid van de middelen antwoorden.