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:

  1. Maak een nieuwe iDEAL QR code en toon deze aan uw consument(en).. (Aanmaak Methode)
  2. De consument scant de QR code met diens bank-app.
  3. De transactiedetails worden getoond aan de consument en, wanneer zo ingesteld, krijgt de kans om het bedrag aan te passen.
  4. De consument bevestigt de transactie met diens bank-app en uw systeem wordt op de hoogte gesteld.
  5. 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
minAmount Het minimum transactiebedrag dat de consument mag kiezen in het geval amountChangeable = 1. Kan leeggelaten worden in het geval amountChangeable = 0. 2500
maxAmount 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
2021-04-07 06:27:31
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

Key Waarde
amount Amount too low, the minimum is set to: 49 - 25 given.
description Description cannot be blank.

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."]}}

Controleer in geval van fouten of de parameters goed zijn overgenomen uit de documentatie. Als dit het geval lijkt te zijn, neem dan contact op met DigiWallet. Vermeldt de aanroep en de foutmelding.

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:
  • Active
  • Expired
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

Key Waarde
qrCodeID There is no QR code for this ID.

Voorbeeld rauwe respons

{"status":1,"message":"Validation failed","errors":{"qrCodeID":["There is no QR code for this ID."]}}

Controleer in geval van fouten of de parameters goed zijn overgenomen uit de documentatie. Als dit het geval lijkt te zijn, neem dan contact op met DigiWallet. Vermeldt de aanroep en de foutmelding.

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:
  • Expired

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

Key Waarde
qrCodeID There is no QR code for this ID.

Voorbeeld rauwe respons

{"status":1,"message":"Validation failed","errors":{"qrCodeID":["There is no QR code for this ID."]}}

Controleer in geval van fouten of de parameters goed zijn overgenomen uit de documentatie. Als dit het geval lijkt te zijn, neem dan contact op met DigiWallet. Vermeldt de aanroep en de foutmelding.