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
| | | |
---|
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. bijv.: 961 Zie ook Overzicht | Interbestuurlijke Producten- en Dienstencatalogus (IPDC) | 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. | 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
| | | |
---|
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: 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.
| |
---|
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
| | |
---|
orderID | Het orderID identificeert het order. U kiest dit zelf. Bijv. UUID v4 om een uniek orderID aan te maken | string |
Optionele attributen
| | |
---|
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.
| |
---|
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:
| | | |
---|
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.
| |
---|
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.
| | |
---|
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.
| | |
---|
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: 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 Overzicht | Interbestuurlijke Producten- en Dienstencatalogus (IPDC) | 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 | 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.
| | |
---|
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
| | |
---|
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: bijv.: nl_BE Indien u dit veld leeg laat, wordt er bij default nl_BE gehanteerd. | String |
status | De status van de betaling: | String |
Schema: PaymentStatus
Dit is de respons wanneer de klant de status(sen) opvraagt van een welbepaald paymentID.
| | |
---|
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: | string |
Schema: Page meta data
| | |
---|
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 |