Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Info

Een koppeling met de Betaalmodule aanvragen

Over de Betaalmodule-API

Aspect

Beschrijving

Naam component waarvoor API voorzien wordt

Betaalmodule

Doel

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.

Specificaties API

Zie hieronder: https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/6044352886/Specificaties+Betaalmodule-API#OpenAPI-specificaties

Link met de Aanvraagmodule

Zie ook https://vlaamseoverheid.atlassian.net/l/cp/WwW19fQ2


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

inc-drawio
2319156034imgPageId1
mVer2
simple0
zoom1
simpleinComment0
pageId23158464726044352886
custContentId6451397399
diagramDisplayNamehigh-level-diagram-bm.drawio
lbox1
diagramDisplayNamecontentVerBetalen na order1
hiResPreviewrevision01
baseUrlhttps://vlaamseoverheid.atlassian.net/wiki
diagramNameDiagram zonder titelhigh-level-diagram-bm.drawio
6044352886pCenter0aspectBoNotAUKLwJajB4BIrTG 1
width1031
includedDiagramlinks
tbstyle
aspectHashheightb523887f8ba73dea2c24ea456be46f1c51805b02
linksauto
tbstyletop
height579

...

580

Stroomdiagram creatie betaallink

In dit stroomdiagram worden de volgende stappen geïllustreerd:

  1. 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.

  2. 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).

  3. De PSP creëert een betaallink en geeft die terug aan de betaalback-end van Digitaal Vlaanderen.

  4. De betaalback-end transformeert de betaallink in een QR-code.

  5. Tot slot worden de betaallink en de QR-code weergegeven in de front-end zodat de gebruiker kan betalen via de gekozen betaalmogelijkheid.

Drawio
links
border1
zoom1
simple0
inComment0
custContentId6049890940
pageId6044352886
custContentId6049890940
lbox1
diagramDisplayNamecreatie betaallink
contentVer4
revision4
baseUrlhttps://vlaamseoverheid.atlassian.net/wiki
diagramNamecreatie betaallink
pCenter0
width562
tbstyleheight452.6666259765625

Stroomdiagram betaalstatus order opvragen

...

U kunt zo nagaan wat de status van de betaling is: voldaan of niet voldaan.

Drawio
links
border1
zoom1
simple0
inComment0
custContentId6050251043
pageId6044352886
custContentId6050251043
lbox1
diagramDisplayNameopvragen status order
contentVer8
revision8
baseUrlhttps://vlaamseoverheid.atlassian.net/wiki
diagramNameopvragen status order
pCenter0
width521
tbstyleheight332

Stroomdiagram betaalstatus a.d.h.v. paymentID opvragen

Drawio
tbstyle
border1
zoom1
simple0
inComment0
custContentId6098453091
pageId6044352886custContentId6098453091
lbox1
diagramDisplayNameopvragen status paymentId
contentVer3
revision3
baseUrlhttps://vlaamseoverheid.atlassian.net/wiki
diagramNameopvragen status paymentId
pCenter0
width551links
height332

Open API-specificaties

...

Swagger integration
defaultModelRenderingmodel
urlhttps://api.betalingen.vlaanderen.be/documentation/api/1.%20Payment

Productie OpenAPI specificatie: https://api.betalingen.tni-vlaanderen.be/documentation/swagger-ui/index.html?configUrl=%2Fdocumentation%2Fswagger.json%2Fswagger-config&urls.primaryName=payment#/Onboarding/validate

...

Info

OpenAPI specificatie volgende versie betaalmodule

Op onze Test-en-Integratie (TNI) omgeving vindt u de volgende versie van de OpenAPI specificatie die weldra naar productie gaat: https://api.betalingen

...

.tni-vlaanderen.be/documentation/swagger-ui/index.html?configUrl=%2Fdocumentation%2Fswagger.json%2Fswagger-config&urls.primaryName=payment#/Onboarding/validate

Functionele omschrijving API

Note

Deze documentatie wordt afgebouwd ter voordele van de OpenAPI specificatie, gelieve dit enkel nog te gebruiken als backup of bijkomende info.

Expand
titleFunctionele omschrijving API

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?

orderID

Het orderID identificeert het order. U kiest dit zelf.

Bijv. UUID v4 om een uniek orderID aan te maken

De maximale lengte van dit veld telt 36 karakters/ tekens.

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.

De maximale lengte van dit veld telt 36 karakters/tekens.

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.

bijv.: 961

Zie ook https://productencatalogus.vlaanderen.be/

String van 3, 4 of 5 cijfers = IPDC-code

Ja

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.

Dit veld moet minimaal 10 karakters tellen.

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

Dit veld moet minimaal 10 karakters tellen.

String van 10 cijfers (KBO), zonder interpunctie

OraFin -aansluiting EN customerType = KBO: ja

Anders: nee

Optionele attributen

Attribuut

Omschrijving

Type (string?)

Verplicht?

descriptionText

De beschrijving van het betalingsverzoek. POM zal deze weergeven in het betalingsscherm.

De maximale lengte van dit veld telt 128 karakters/ tekens.

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

De maximale lengte van dit veld telt 255 karakters/ tekens.

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.

De maximale lengte van dit veld telt 36 karakters/tekens.

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.

Alleen in te vullen om af te wijken van de standaardwaarde die tijdens de aansluiting werd gekozen.

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

Dit veld moet minimaal 11 karakters tellen.

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

Dit veld moet minimaal 10 karakters tellen.

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

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

orderID

Het orderID identificeert het order. U kiest dit zelf.

Bijv. UUID v4 om een uniek orderID aan te maken

De maximale lengte van dit veld telt 36 karakters/ tekens.

string

Optionele attributen

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

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?

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

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

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

orderID

Het orderID identificeert het order. U kiest dit zelf.

Bijv. UUID v4 om een uniek orderID aan te maken

De maximale lengte van dit veld telt 36 karakters/ tekens.

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.

De maximale lengte van dit veld telt 36 karakters/tekens.

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.

bijv.: 961

Zie ook https://productencatalogus.vlaanderen.be/

String van 3, 4 of 5 cijfers = IPDC-code

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.

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

Dit veld moet minimaal 10 karakters tellen.

String van 10 cijfers (RRN), zonder interpunctie

kboNumber

Het KBO-nummer voor een professionele aankoop.

bijv.: 7682949223

Dit veld moet minimaal 10 karakters tellen.

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

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

...

additionalLinks

Bijkomende links

...

SMS

...

QR

...

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

...

Attribuut

...

omschrijving

...

Type

...

paylink

...

Dit is de paylink-/ betaallink-URL voor het kanaal in kwestie.

...

string

...

paylinkShort

...

.

string

Schema: Payment

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.

De maximale lengte van dit veld telt 36 karakters/tekens.

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

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

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.

Integer