iDEAL QR API
Met de REST API voor iDEAL QR kunt u snel en gemakkelijk QR codes genereren die een consument kan scannen om automatisch een iDEAL transactie op te starten.
De iDEAL QR flow in het kort:
- Maak een nieuwe iDEAL QR code en toon deze aan uw consument(en).. (Aanmaak Methode)
- De consument scant de QR code met diens bank-app.
- De transactiedetails worden getoond aan de consument en, wanneer zo ingesteld, krijgt de kans om het bedrag aan te passen.
- De consument bevestigt de transactie met diens bank-app en uw systeem wordt op de hoogte gesteld.
- U kunt de iDEAL QR code ten alle tijden stopzetten. (Stop Methode)
HTTP Bearer Authenticatie
Deze API vereist HTTP Bearer authenticatie. (Lees meer...) Dit betekent dat uw verzoeken aan deze API een extra HTTP header met uw organisatie's API sleutel nodig hebben om geaccepteerd te worden.
U kunt uw organisatie's API sleutel vinden in uw Organisatie Dashboard.
Een voorbeeld van de HTTP header is als volgt:
Authorization: Bearer 12a34bc5de67f8g9012345678
RESTful API
Dit is een RESTful API. Dit betekent dat de API het RESTful formaat voor webservices volgt (Lees meer...)
Het respons formaat van deze API's is in (JSON).
Een typische respons is een JSON-geëncodeerde array met een status
integer om aan te geven of de aanroep gelukt is of niet, en een message
string met een beschrijving van wat er is gebeurd.
Naast deze standaard elementen kan een API natuurlijk API-specifieke informatie teruggeven. e.g. transactionID
integer voor het maken van een transactie. Of een nested errors
array
waarin gedetailleerde validatiefouten staan.
De HTTP response codes van de RESTful API's volgen de onderstaande logica:
HTTP Status Code | Gebruikt in reactie op |
---|---|
200 (Success) | Een succesvol verwerkt verzoek dat ook informatie teruggeeft |
201 (Created) | Een succesvol verwerkt aanmaak verzoek |
202 (Accepted) | Een succesvol geaccepteerd job verzoek |
400 (Bad Request) | Foutieve input parameters / validatiefouten |
401 (Unauthorized) | Foutieve inloggegevens |
404 (Not Found) | Object kon niet gevonden worden |
405 (Method Not Allowed) | Methode is niet ondersteund in deze API |
500 (Internal Server Error) | Er is een probleem opgetereden in DigiWallet's servers |
Aanmaak Methode Maak nieuwe iDEAL QR code
Om een nieuwe iDEAL QR code te maken, roep de volgende API aan via HTTP POST
.
https://api.digiwallet.nl/ideal/qr
Met de volgende parameters (* = verplicht):
Variabele | Toelichting | Voorbeeld |
---|---|---|
outletID* | Het ID van de outlet waarop u de QR code wilt registreren. | 12345 |
amount* | Het bedrag van de transactie die gemaakt wordt door het scannen van de QR code, in centen. | 5000 |
oneoff |
Of deze QR code eenmalige te gebruiken, of herbruikbaar is. Staat standaard op 0 .
|
1 |
amountChangeable |
Of het de consument toegestaan is het bedrag vooraf te wijzigen. Staat standaard op 0 .
|
1 |
amountMin |
Het minimum transactiebedrag dat de consument mag kiezen in het geval amountChangeable = 1 .
Kan leeggelaten worden in het geval amountChangeable = 0 .
|
2500 |
amountMax |
Het maximum transactiebedrag dat de consument mag kiezen in het geval amountChangeable = 1 .
Kan leeggelaten worden in het geval amountChangeable = 0 .
|
7500 |
description* | Beschrijving voor op de consument's bankafschrift. | Dontatie aan het weeshuis |
expiration* |
Datum en tijd in de toekomst waarop de QR code zal verlopen. Formaat: YYYY-MM-DD
HH:MM:SS
|
2025-03-28 21:27:11 |
size* |
De grootte in pixels van de QR code afbeelding. Deze waarde wordt gebruikt voor beiden de breedte alswel de hoogte. |
500 |
returnURL* |
De locatie waar uw consument naartoe wordt gestuurd na het afronden van de betaling. De parameters die worden toegevoegd aan deze URL zijn hetzelfde als in de reguliere (iDEAL API). |
https://www.myshop.nl/thankYouPage |
cancelURL |
De locatie waar uw consument naartoe wordt gestuurd na het annuleren van de betaling. De parameters die worden toegevoegd aan deze URL zijn hetzelfde als in de reguliere (iDEAL API). Als u dit veld leeg laat zal de returnURL hiervoor in de plaats worden gebruikt. |
https://www.myshop.nl/cancelPage |
reportURL* |
Het server script dat wordt aangeroepen wanneer de consument de transactie afrond. Dit verzoek wordt uitgevoerd via HTTP POST .De parameters die worden toegevoegd aan deze URL zijn hetzelfde als in de reguliere (iDEAL API). Gebruik de iDEAL API Check Method om de authenticiteit van de reportURL callback te bevestigen. |
https://www.myshop.nl/reportTransaction |
U krijgt dan een JSON-geëncodeerde array terug met de volgende inhoud:
Key | Waarde |
---|---|
status | 0 |
message | QR code successfully created |
qrCodeID | ID van de gemaakte QR code
|
qrCodeURL | URL van de QR code afbeelding
|
Voorbeeld rauwe respons
{"status":0,"message":"QR code successfully created","qrCodeID":12345,"qrCodeURL":"https://qr2.ideal.nl/ideal-qr/qr/get/5693727d-c230-4b27-856b-2db8902943ab"}
U kunt nu de qrCodeID
en de qrCodeURL
in uw database en toon de QR code aan uw consument(en).
In het geval van één of meer fouten krijgt u een JSON-geëncodeerde array respons met de volgende inhoud:
Key | Waarde | ||||||
---|---|---|---|---|---|---|---|
status | 1 | ||||||
message | Validation failed | ||||||
errors |
Nested JSON-geëncodeerde array met validatiefouten
Voorbeeld
|
Voorbeeld rauwe respons
{"status":1,"message":"Validation failed","errors":{"initialAmount":["Amount too low, the minimum is set to: 49 - 25 given."],"description":["Description cannot be blank."]}}
Check Methode Check QR code
Om de status van de QR code te controleren, roep de volgende API aan via HTTP GET
.
https://api.digiwallet.nl/ideal/qr/<outletID>/<qrCodeID>
De query string parameters kunt u invullen als volgt (* = vereist):
Variabele | Toelichting | Voorbeeld |
---|---|---|
outletID* | Het ID van de outlet waarop de QR code is geregistreerd. | 39995534 |
qrCodeID* | Het ID van de QR code. | 12345678 |
U krijgt dan een JSON-geëncodeerde array terug met de volgende inhoud:
Key | Waarde |
---|---|
status | 0 |
message | QR code successfully checked |
qrCodeStatus |
Huidige status van de QR code, opties zijn als volgt:
|
qrCodeURL | De URL van de QR code afbeelding. |
Voorbeeld rauwe respons
{"status":0,"message":"QR code successfully checked","qrCodeStatus":"Active","qrCodeURL":"https://qr2.ideal.nl/ideal-qr/qr/get/5693727d-c230-4b27-856b-2db8902943ab"}
In het geval van één of meer fouten krijgt u een JSON-geëncodeerde array respons met de volgende inhoud:
Key | Waarde | ||||
---|---|---|---|---|---|
status | 1 | ||||
message | Validation failed | ||||
errors |
Nested JSON-geëncodeerde array met validatiefouten
Voorbeeld
|
Voorbeeld rauwe respons
{"status":1,"message":"Validation failed","errors":{"qrCodeID":["There is no QR code for this ID."]}}
Stop Methode Stop QR code
Om een actieve QR code vroegtijdig stop te zetten, roep de volgende API via HTTP DELETE
.
https://api.digiwallet.nl/ideal/qr/<outletID>/<qrCodeID>
De query string parameters kunt u invullen als volgt (* = vereist):
Variabele | Toelichting | Voorbeeld |
---|---|---|
outletID* | Het ID van de outlet waarop de QR code is geregistreerd. | 39995534 |
qrCodeID* | Het ID van de QR code. | 12345678 |
U krijgt dan een JSON-geëncodeerde array terug met de volgende inhoud:
Key | Waarde |
---|---|
status | 0 |
message | QR code successfully terminated |
qrCodeStatus |
Nieuwe status van de QR code, opties zijn als volgt:
|
Voorbeeld rauwe respons
{"status":0,"message":"QR code successfully terminated","qrCodeStatus":"Expired"}
In het geval van één of meer fouten krijgt u een JSON-geëncodeerde array respons met de volgende inhoud:
Key | Waarde | ||||
---|---|---|---|---|---|
status | 1 | ||||
message | Validation failed | ||||
errors |
Nested JSON-geëncodeerde array met validatiefouten
Voorbeeld
|
Voorbeeld rauwe respons
{"status":1,"message":"Validation failed","errors":{"qrCodeID":["There is no QR code for this ID."]}}