Deze technische documentatie is bestemd voor lokale besturen en Vlaamse entiteiten die de Betaalmodule van Digitaal Vlaanderen willen gebruiken om klanten te laten betalen voor een specifieke digitale dienstverlening.
De API van de Betaalmodule bestaat uit 2 onderdelen:
Deel om een betaallink met bijhorende QR-code aan te maken: de eindgebruiker kan betalen voor een aankoop in de front-end.
Deel om de status van een specifiek orderID op te vragen: u kunt op elk moment de status van de betaling voor een bepaald order opvragen
Met deze API kunt u een betaallink aanmaken zodat uw klanten meteen kunnen betalen voor een dienstverlening (order). U kunt ook statusupdates krijgen over de betaling van het order.
Klant
Vlaamse overheidsdiensten
Lokale besturen
Gevolg
Via de API kan er een betaallink met QR-code worden aangemaakt op basis van de doorgegeven betaalgegevens.
Via de API kan een lijst met betalingen en bijhorende data voor een orderID worden opgevraagd. Hiermee kunt u de status van de betaling checken.
Bijv. Kwalificatiekaart bestuurder van Departement Mobiliteit en Openbare Werken waar bij de aanvraag van de kwalificatiekaart ook een betaling nodig. Hiervoor gebruikt DMOW zowel de Aanvraag- als de Betaalmodule.
High-level stroomdiagram Betaalmodule
Stroomdiagram creatie betaallink
In dit stroomdiagram worden de volgende stappen geïllustreerd:
Zodra de gebruiker een order (bestelling) plaatst, worden de betaalparameters in de front-end bepaald en vervolgens doorgegeven aan de betaalback-end van Digitaal Vlaanderen.
Aan de hand van deze betaalparameters (bijv. bedrag, orderID,..), maakt de betaalback-end het betaalverzoek (payment request) aan en stuurt dit door naar de Payment Service Provider (PSP).
De PSP creëert een betaallink en geeft die terug aan de betaalback-end van Digitaal Vlaanderen.
De betaalback-end transformeert de betaallink in een QR-code.
Tot slot worden de betaallink en de QR-code weergegeven in de front-end zodat de gebruiker kan betalen via de gekozen betaalmogelijkheid.
Stroomdiagram betaalstatus order opvragen
U kunt op elk moment de betaalstatus van een order opvragen bij de betaalback-end van Digitaal Vlaanderen door het orderID mee te geven. Op basis daarvan krijgt u een lijst met betaling(en) die bij dat order horen. Aanvankelijk zal aan 1 order 1 betaling gekoppeld zijn.
U kunt zo nagaan wat de status van de betaling is: voldaan of niet voldaan.
Deze documentatie wordt afgebouwd ter voordele van de OpenAPI specificatie, gelieve dit enkel nog te gebruiken als backup of bijkomende info.
Een betaallink met QR-code aanmaken
Hieronder het overzicht van de attributen en de bijhorende omschrijving. Op basis van de API, wordt er een betaallink met bijhorende QR-code aangemaakt. Deze QR-code wordt weergegeven in de front-end zodat de burger kan scannen en betalen voor zijn order.
Verplichte attributen
Attribuut
Omschrijving
Type (string?)
Verplicht?
Attribuut
Omschrijving
Type (string?)
Verplicht?
orderID
Het orderID identificeert het order. U kiest dit zelf.
Bijv. UUID v4 om een uniek orderID aan te maken
string
Ja
amount
Het te betalen bedrag voor het order tot op 2 cijfers na de komma
Decimal, tot op 2 cijfers na de komma
Ja
communication
Indien u geen OraFin-aansluiting heeft, moet in dit veld een vrije mededeling meegegeven worden.
string
OraFin-aansluiting: nee
Geen OraFin-aansluiting: ja
ipdcCode
De IPDC-code van het product.
Dit veld is altijd verplicht. Als u een OraFin-aansluiting heeft, wordt de IPDC-code gebruikt voor de boekhouding in OraFin.
Gebruik hier de code uit de IPDC-dienstencatalogus.
Geeft mee of de betaling voor een particuliere of een professionele aankoop gebeurt.
Mogelijke waarden zijn KSZ (voor een particuliere aankoop) of KBO (voor een professionele aankoop).
Enum (KSZ, KBO)
OraFin-aansluiting: ja
Geen OraFin-aansluiting: nee
insz
Het rijksregisternummer voor een particuliere aankoop.
String van 10 cijfers (RRN), zonder interpunctie
OraFin-aansluiting EN customerType = KSZ: ja
Anders: nee
kboNumber
Het KBO-nummer voor een professionele aankoop.
bijv.: 7682949223
String van 10 cijfers (KBO), zonder interpunctie
OraFin -aansluiting EN customerType = KBO: ja
Anders: nee
Optionele attributen
Attribuut
Omschrijving
Type (string?)
Verplicht?
Attribuut
Omschrijving
Type (string?)
Verplicht?
descriptionText
De beschrijving van het betalingsverzoek. POM zal deze weergeven in het betalingsscherm.
string
Neen
descriptionUrl
Plaatst een HTML-link achter de beschrijving van het betalingsverzoek om bijv. te verwijzen naar een informatiepagina over het product of de dienst
URL
Neen
dueDate
De uiterste betaaldatum
Deze datum hoeft alleen meegegeven te worden voor wie wil afwijken van de standaardwaarde die werd meegegeven bij de aansluiting.
De betaling gebeurt in principe meteen, dus de dueDate moet minstens de datum van morgen zijn.
Als er geen dueDate wordt meegegeven, wordt de geldigheidsduur van de betaallink genomen.
Datum in ISO 8601-formaat, bijv. 2023-05-30)
Neen
communication
Indien u geen OraFin-aansluiting heeft, moet in dit veld een vrije mededeling meegegeven worden.
string
OraFin-aansluiting: nee
Geen OraFin-aansluiting: ja
paymentMethod
Standaard worden de betaalmethoden aangeboden die tijdens de aansluiting werden gekozen.
Dit veld moet alleen meegeven worden om af te wijken van de standaard betaalmethoden die tijdens de aansluiting werden gekozen.
Neem contact op met Digitaal Vlaanderen om te weten welke betaalmethoden op uw contract zijn toegestaan.
Enum of CSV-lijst van Enum
payconiq, bancontact, visa , mastercard
bijv: payconiq,visa
Neen
expiryDate
De expiryDate (tijdstip) moet in de toekomst te liggen.
Dit zijn de datum en het tijdstip waarop het betalingsverzoek vervalt in UTC-formaat.
Het is niet nodig zowel de dueDate als de expiryDate in te vullen. De expiryDate is voldoende.
Indien dit veld leeggelaten wordt, wordt de geldigheidsduur van de betaallink worden overgenomen uit het aansluitingsformulier.
Datum en Tijd in ISO 8601-formaat, UTC tijdzone,
bijv. 2023-05-30T07:11:34.542Z
Neen
language
De taal van het betalingsverzoek:
2 karakters voor de taalcode volgens ISO 639
gevolgd door '_'
gevolgd door 2 karakters voor de landcode volgens ISO 3166-2
bijv.: nl_BE
U mag dit veld leeg laten. Er wordt dan by default nl_BE gebruikt.
Enum: nl_be, en_BE, fr_BE
Neen
redirectUrl
U kunt een URL doorgeven naar waar er geredirect wordt na het afronden van een online betaling. Zo kan de betaler naar de gewenste context worden gestuurd.
U kunt ook een vaste URL configureren bij de PSP.
URL
Neen
customerType
Geeft mee of de betaling voor een particuliere of een professionele aankoop gebeurt.
Mogelijke waarden zijn KSZ (voor een particuliere aankoop) of KBO (voor een professionele aankoop).
Enum (KSZ, KBO)
OraFin-aansluiting: ja
Geen OraFin-aansluiting: nee
insz
Het rijksregisternummer voor een particuliere aankoop.
bijv.: 82200501055
String van 10 cijfers (RRN), zonder interpunctie
OraFin-aansluiting EN customerType = KSZ: ja
Anders: nee
kboNumber
Het KBO-nummer voor een professionele aankoop.
bijv.: 7682949223
String van 10 cijfers (KBO), zonder interpunctie
OraFin -aansluiting EN customerType = KBO: ja
Anders: nee
Mogelijke responses
Hieronder een overzicht van de mogelijke responses op de API en de bijhorende beschrijving per respons.
Respons
Beschrijving
Respons
Beschrijving
200
OK
Succesvolle respons, er wordt een betaallink en QR-code teruggegeven.
400
Bad request
Foutmelding, er wordt geen betaallink en QR-code teruggegeven.
403
Forbidden
Foutmelding, er wordt geen betaallink en QR-code teruggegeven.
404
Not found
Foutmelding, er wordt geen betaallink en QR-code teruggegeven.
500
Internal Server Error
Foutmelding, er wordt geen betaallink en QR-code teruggegeven.
503
Service Unavailable
Foutmelding, er wordt geen betaallink en QR-code teruggegeven.
De betaling(en) voor een bestelling (order) opmaken
U geeft een orderID door. Op basis van dit orderID geeft de betaalback-end van Digitaal Vlaanderen een lijst terug van de bijhorende betaling(en) en informatie over de de status van de betaling.
Verplichte attributen
Attribuut
Omschrijving
Type
Attribuut
Omschrijving
Type
orderID
Het orderID identificeert het order. U kiest dit zelf.
Bijv. UUID v4 om een uniek orderID aan te maken
string
Optionele attributen
Attribuut
Omschrijving
Type
Attribuut
Omschrijving
Type
Limit
Dit veld bevat de paginagrootte van de respons en is standaard ingesteld op 10.
Integer
Offset
Dit veld bevat de pagina-offset van de response, en is standaard ingesteld op 0.
Integer
Mogelijke responses
Hieronder een overzicht van de mogelijke responses op de API en de beschrijving per respons.
Respons
Beschrijving
Respons
Beschrijving
200
OK
Succesvolle respons, er wordt een lijst met de bijhorende betaling(en) en gegevens voor het orderID teruggegeven.
400
Bad Request
Foutmelding, er wordt geen lijst met de bijhorende betaling(en) en gegevens voor het orderID teruggegeven.
403
Forbidden
Foutmelding, er wordt geen lijst met de bijhorende betaling(en) en gegevens voor het orderID teruggegeven.
404
Not Found
Foutmelding, er wordt geen lijst met de bijhorende betaling(en) en gegevens voor het orderID teruggegeven.
451
Unavailable For Legal Reasons
Foutmelding, er wordt geen lijst met de bijhorende betaling(en) en gegevens voor het orderID teruggegeven.
500
Internal Server Error
Foutmelding, er wordt geen lijst met de bijhorende betaling(en) en gegevens voor het orderID teruggegeven.
503
Service Unavailable
Foutmelding, er wordt geen lijst met de bijhorende betaling(en) en gegevens voor het orderID teruggegeven.
De (online) betaalstatus voor een betaling opvragen
U geeft een paymentID door om de bijhorende betaalstatus(sen) op te vragen. De volgende statussen worden opgevraagd:
Status van de betaling
Status van de online afhandeling van de betaling
Attribuut
Omschrijving
type?
Verplicht?
Attribuut
Omschrijving
type?
Verplicht?
paymentID
Het paymentID identificeert de betaling zoals gegeven door de Betaalmodule.
String
Ja
Mogelijke responses
Hieronder een overzicht van de mogelijke responses op de API en de beschrijving per respons.
Respons
Beschrijving respons
Respons
Beschrijving respons
200
OK
Succesvolle respons, er wordt een lijst met bijhorende status(sen) gegeven op basis van het paymentID.
400
Bad request
Foutmelding, er wordt geen lijst met bijhorende status(sen) gegeven op basis van het paymentID.
403
Forbidden
Foutmelding, er wordt geen lijst met bijhorende status(sen) gegeven op basis van het paymentID.
404
Not Found
Foutmelding, er wordt geen lijst met bijhorende status(sen) gegeven op basis van het paymentID.
451
Unavailable For Legal Reasons
Foutmelding, er wordt geen lijst met bijhorende status(sen) gegeven op basis van het paymentID.
500
Internal Server Error
Foutmelding, er wordt geen lijst met bijhorende status(sen) gegeven op basis van het paymentID.
503
Service Unavailable
Foutmelding, er wordt geen lijst met bijhorende status(sen) gegeven op basis van het paymentID.
Functionele omschrijving schema’s API
U komt zelf niet in aanraking met de complexiteit van de payment service provider (PSP). Digitaal Vlaanderen interageert met de PSP via de onderstaande API schema’s
Schema: ErrorResponse
Foutmelding van de Payment Service Provider die wordt overgenomen in de API van Digitaal Vlaanderen.
Attribuut
Omschrijving
Type
Attribuut
Omschrijving
Type
status
Status van de respons
integer
type
Type error/ fout
string
title
Titel
string
detail
Detailinformatie over de error/ fout
string
instance
Plaats waar de error/ fout zich precies bevindt
string
Schema: Payment Request
Payment request die de Payment Service Provider ontvangt van de betaalback-end van Digitaal Vlaanderen.
Attribuut
Omschrijving
Type
Attribuut
Omschrijving
Type
orderID
Het orderID identificeert het order. U kiest dit zelf.
Bijv. UUID v4 om een uniek orderID aan te maken
string
descriptionText
De beschrijving van het betalingsverzoek, POM toont deze beschrijving in het betalingsscherm.
string
descriptionUrl
Plaatst een HTML-link achter de beschrijving van het betalingsverzoek om bijv. te verwijzen naar een informatiepagina over het product of de dienst
string
amount
Het te betalen bedrag voor het order tot op 2 cijfers na de komma
Decimal, tot op 2 cijfers na de komma
dueDate
De uiterste betaaldatum
De betaling gebeurt in principe meteen, dus de dueDate zal gewoonlijk de datum van morgen zijn.
De duedate dient minimaal 1 dag in de toekomst te liggen.
string
communication
Indien u geen OraFin-aansluiting heeft, moet in dit veld een vrije mededeling meegegeven worden.
string
paymentMethod
Als het contract met de Payment Service Provider toestaat om dit veld leeg te laten, kan de betaler elke methode gebruiken die op het contract voorzien is.
U kunt ervoor kiezen deze methodes te beperken door een specifieke methode mee te sturen.
Neem contact op met de PSP om te weten welke methoden op uw contract zijn toegestaan.
string
expiryDate
De datum waarop het betalingsverzoek vervalt in UTC-formaat. Deze datum moet groter zijn of gelijk zijn aan de dueDate + 1 dag.
Indien dit veld leeggelaten wordt, zal by default de vervaldatum (expirydate) worden overgenomen uit het aansluitingsformulier.
string
language
De taal van het betalingsverzoek:
2 karakters voor de taalcode volgens ISO 639
gevolgd door '_'
gevolgd door 2 karakters voor de landcode volgens ISO 3166-2
bijv.: nl_BE
Indien u dit veld leeg laat, wordt er bij default nl_BE gehanteerd.
string
ipdcCode
De IPDC-code van het product.
Dit veld is altijd verplicht. Als u een OraFin-aansluiting heeft, wordt de IPDC-code gebruikt voor de boekhouding in OraFin.
Gebruik hier de code uit de IPDC-dienstencatalogus.
U kunt een URL doorgeven naar waar er geredirect wordt na het afronden van een online betaling. Zo kan de betaler naar de gewenste context worden gestuurd.
U kunt ook een vaste URL configureren bij de PSP.
string
customerType
Geeft mee of de betaling voor een particuliere of een professionele aankoop gebeurt.
Mogelijke waarden zijn KSZ (voor een particuliere aankoop) of KBO (voor een professionele aankoop).
Enum (KSZ, KBO)
insz
Het rijksregisternummer voor een particuliere aankoop.
bijv.: 82200501055
String van 10 cijfers (RRN), zonder interpunctie
kboNumber
Het KBO-nummer voor een professionele aankoop.
bijv.: 7682949223
String van 10 cijfers (KBO), zonder interpunctie
Schema: Payment Request Response
Dit is de respons van de PSP op de payment request die Digitaal Vlaanderen creëert op basis van de betaalgegevens (data, orderID,..) en vervolgens doorgeeft aan de PSP.
Attribuut
Omschrijving
Type
Attribuut
Omschrijving
Type
orderID
Het orderID identificeert het order. U kiest het orderID zelf.
string
paymentID
Het paymentID identificeert de betaling zoals meegegeven door de Betaalmodule.
string
pspPaymentID
Het pspPaymentID identificeert de betaling zoals meegegeven door de Payment Service Provider.
string
paylink
Dit is de betaallink die werd gecreëerd.
string
communication
Indien van toepassing, wordt in dit veld de gestructureerde mededeling geplaatst.
Dit veld wordt alleen teruggegeven voor klanten die een OraFin-aansluiting hebben.
string
error
Foutmelding, indien van toepassing zal er een as-is-fout terugkomen van de payment service provider.
string
Schema: Payment
Attribuut
Omschrijving
Type
Attribuut
Omschrijving
Type
orderID
Het orderID identificeert het order. U kiest het orderID zelf.
String
paymentID
Het paymentID identificeert de betaling zoals meegegeven door de Betaalmodule.
string
pspPaymentID
Het pspPaymentID identificeert de betaling zoals meegegeven door de Payment Service Provider.
String
senderContract Number
Het contractnummer waaronder het betalingsverzoek ontvangen is.
String
descriptionText
De beschrijving/het label van het betalingsverzoek.
String
descriptionUrl
Veld waarmee u een HTLM-link plaatst achter de beschrijving van het betalingsverzoek om bijv. te verwijzen naar een informatiepagina over het product/ departement
String
amount
Het te betalen bedrag voor het order tot op 2 cijfers na de komma
Decimal, tot op 2 cijfers na de komma
currency
De munteenheid van het betalingsverzoek, dit zal altijd EUR (= euro) zijn.
String
documentDate
De creatiedatum van het betalingsverzoek, in het formaat YYYY-MM-DD.
String
dueDate
De uiterlijke betalingsdatum
De betaling gebeurt in principe meteen, dus de dueDate zal gewoonlijk de datum van morgen zijn.
String
paymentType
Het type betaling/document.
Dit zal in de meeste gevallen “Invoice” zijn.
String
communication
Indien u geen OraFin-aansluiting heeft, moet in dit veld een vrije mededeling meegegeven worden.
string
paymentMethod
De betalingsmethode die werd gekozen om de betaling uit te voeren, bijv. Visa.
String
paymentDate
Het tijdstip waarop waarop de betaalstatus op COMPLETED werd gezet, in UTC-formaat.
String
expiryDate
De datum waarop het betalingsverzoek vervalt in UTC-formaat. Deze datum moet groter zijn of gelijk zijn aan de dueDate + 1 dag.
Indien dit veld leeggelaten wordt, zal by default de vervaldatum (expirydate) worden overgenomen uit het aansluitingsformulier.
String
language
De taal van het betalingsverzoek:
2 karakters voor de taalcode volgens ISO 639
gevolgd door '_'
gevolgd door 2 karakters voor de landcode volgens ISO 3166-2
bijv.: nl_BE
Indien u dit veld leeg laat, wordt er bij default nl_BE gehanteerd.
String
status
De status van de betaling:
NOT_COMPLETED
COMPLETED
String
Schema: PaymentStatus
Dit is de respons wanneer de klant de status(sen) opvraagt van een welbepaald paymentID.
Attribuut
Omschrijving
Type
Attribuut
Omschrijving
Type
onlineStatus
Duidt de status van de online afhandeling van de betaling aan. De mogelijke waarden zijn:
SUCCESS
IN_PROGRESS
FAILURE
Zolang de online betaling nog in uitvoering is, zal dit element ontbreken.
string
status
Duidt de status van de betaling aan. Momenteel zijn de mogelijke waarden:
WAITING
COMPLETED
string
Schema: Page meta data
Attribuut
Omschrijving
Type
Attribuut
Omschrijving
Type
offset
Dit veld bevat de paginaoffset. Dit staat default op 0, en haalt de eerste pagina op.
Een offset van 1 haalt de tweede pagina op, als die er is, etc.
Integer
size
Dit veld bevat de paginagrootte. Dit staat default op 10, maar kan worden aangepast met de limit parameter in de request.
Integer
totalItems
Dit is het totaal aantal gevonden items. Wanneer dit getal groter is dan de paginagrootte kunt u met de offset-parameter in de request de volgende pagina opvragen.
