iDEAL QR – Merchant Implementatie Guidelines (NL)
Version: 1.5
Date: 19-02-2018
Versies
Inhoud
1. Wat is iDEAL QR?
Naast het online domein kan iDEAL ook gebruikt worden vanuit het fysieke domein met behulp van iDEAL QR. Merchants kunnen een iDEAL QR code genereren waarmee de consument met behulp van de iDEAL App een iDEAL betaling kan opstarten. De QR code wordt uitsluitend gebruikt voor het opstarten van een reguliere iDEAL mobiel transactie en heeft dus geen functie in de uitvoering van de iDEAL transactie zelf. Daarom kan het iDEAL 4-corner berichtenmodel in tact blijven en worden er alleen componenten toegevoegd in de omgeving daarvan.
iDEAL QR kent, naast de bekende iDEAL protocollen tussen de Merchant en de Acquirer, drie eigen protocollen tussen de Merchant en een centrale iDEAL QR back-end. Deze protocollen zijn iDEAL QR Generate, iDEAL QR Transaction en iDEAL QR Status. Met het iDEAL QR Generate API protocol kan een Merchant een iDEAL QR-code aanmaken. Met het iDEAL QR Transaction
API protocol wordt, nadat de QR-code gescand is, een iDEAL transactie verzoek gedaan van de QR back-end aan de Merchant en wordt de resulterende IssuerAuthenticatieURL teruggestuurd door de Merchant aan de QR back-end en de iDEAL app. In het iDEAL QR Status API protocol wordt de status van de iDEAL transactie door de QR back-end bij de Merchant opgevraagd.
Onderstaand overzicht geeft de protocollen weer, waarbij de gestippelde lijnen het reguliere iDEAL protocol betreft.
Schematische weergave van de stappen van de iDEAL QR transactie.
2. Registratie en Onboarding
Om gebruik te kunnen maken van iDEAL QR dient een Merchant een iDEAL contract bij een van de bij iDEAL aangesloten Acquiring partijen te hebben. Voor het registreren voor iDEAL QR dient de Merchant met haar Acquirer contact op te nemen en zich te registreren bij de betreffende iDEAL QR back-end. Na registratie kan de Merchant iDEAL QR codes laten genereren en connectie maken met de QR back-end om iDEAL betaalverzoeken uit gescande QR codes te initiëren.
De volgende informatie moet worden geregistreerd bij de Acquiring partij voorafgaand aan het kunnen aanmaken van iDEAL QR codes (mogelijk zijn delen al geregistreerd als onderdeel van iDEAL registratie).
Data-element | Omschrijving |
|---|---|
MerchantID | Aansluitnummer / MerchantID zoals de Merchant bij de Acquirer bekend is. |
legalName | De juridische naam van de Merchant, zoals deze geregistreerd staat bij de Acquirer. |
Merchant API URL's | De URL's van de Merchant waarnaar de QR back-end haar requests stuurt. |
Contact name | Naam van contactpersoon waarmee in geval van operationele problemen contact kan worden opgenomen. |
Contact email | E-mail adres van de contactpersoon |
Contact phone | Telefoonnummer van de contactpersoon |
Na de registratie ontvangt de Merchant van de Acquiring partij:
Data-element | Omschrijving |
|---|---|
Merchant Token | Een geheim identificatienummer specifiek voor de Merchant waarmee hij bij de iDEAL QR back-end kan worden geïdentificeerd en geauthentiseerd. Op basis van dit token kan de Merchant iDEAL QR-codes laten genereren bij de iDEAL QR back-end. |
API URL's QR back-end | De API URL's waarmee de iDEAL QR back-end met de Merchant communiceert. |
Secret signing key | Een geheime symmetrische sleutel waarmee de iDEAL QR back-end haar berichten ondertekent en waarmee de Merchant de inkomende berichten kan authentiseren. Zie paragraaf 9 over veiligheid. |
Let op
De opgegeven Merchant API URL ten behoeve van het iDEAL QR Transaction protocol dient te allen tijde beschikbaar te zijn voor een geslaagde iDEAL QR scan van de Consument. Wanneer de URL niet beschikbaar is kan de Consument via de gescande QR-code geen iDEAL transactie opstarten.
3. Berichtformaat
De specificaties rondom het iDEAL QR protocol berichtenformaat tussen de Merchant en de QR back-end volgen de specificaties zoals gesteld ten behoeve van het standaard iDEAL berichtenformaat. Echter op een aantal punten verschilt deze:
- Er wordt voor de body in het HTTP POST en 200 OK response bericht gebruik gemaakt van het JSON berichtformaat in plaats van XML
- De HTTP header verwijst met content type naar het JSON berichtformaat.
- In berichten vanuit de iDEAL QR back-end wordt een signature meegegeven in de HTTP header met verwijzing x-ideal-qr-hash. Zie paragraaf 9 voor meer informatie over beveiliging en de signing signature.
Voorbeeld (iDEAL QR Generate call):
POST /ideal-qr/v1.0/generate HTTP/1.1Content-type: application/json, charset=UTF-8{"merchant_token": "784aea4c-e36c-4a4b-b164-f9818aaeaf5c","merchant_sub_id": 5,"amount": 24.95,"amount_changeable": false,"description": "Product Y","one_off": false,"expiration": "2016-05-14 00:00","beneficiary": "Organisatie X","purchase_id": "PO1234567","size": 1000}4. Genereren iDEAL QR code – iDEAL QR Generate protocol
Wanneer de Merchant is geregistreerd en het registratie proces heeft doorlopen, kan zij iDEAL QR-codes genereren door middel van het Generate API protocol met de iDEAL QR back-end. In dit protocol worden de benodigde gegevens, die bij de specifieke QR code behoren (zoals het bedrag en de omschrijving) op de iDEAL QR back-end opgeslagen en gekoppeld aan een unieke iDEAL QR ID. De gegenereerde QR-code bevat enkel deze iDEAL QR ID (verpakt in een URL) en dus geen betaalgegevens.
4.1 iDEAL QR Generate API call
Om een iDEAL QR-code te genereren, dient de Merchant de Generate API call uit te voeren. De
Generate API call bestaat uit een JSON bericht dat als body in een HTTP POST request naar de QR back-end URL wordt verstuurd.
De API URL voor de Generate API calls wordt door de iDEAL QR Back-end van de betreffende Acquirer verschaft. Neem hiervoor contact op met je Acquirer. Zie ook hoofdstuk 2.
De tabel hieronder toont de velden van het Generate API call en hun formaat.
Naam | Omschrijving | Formaat |
|---|---|---|
| Dit is het ID dat de Merchant heeft ontvangen bij de onboarding bij de QR back-end. Deze identificeert de Merchant bij de QR backend. | AN..36 |
| Het bedrag dat voor de specifieke QR code vooraf is ingevuld. Er wordt een punt (.) gebruikt als decimaalteken. Amount mag geen 0 zijn (iDEAL betalingen van 0 cent zijn niet mogelijk). | DEC (12,2) |
| In dit veld wordt aangegeven of het bedrag aanpasbaar moet zijn voor de Consument. Waarde false als het bedrag niet aanpasbaar moet zijn, true als deze wel aanpasbaar moet zijn. | true/false |
| In dit veld moet een maximaal bedrag worden gegeven als het bedrag aanpasbaar is. Moet groter zijn dan 0 en groter dan "amount" | DEC (12,2) |
| In dit veld kan een minimaal bedrag worden gegeven als het bedrag aanpasbaar is. Moet groter zijn dan 0 en kleiner dan "amount" | DEC (12,2) |
| De omschrijving van de betaling zoals deze wordt getoond en zoals deze in het iDEAL berichten protocol wordt meegegeven. | AN..max 35 |
| In dit veld wordt aangegeven of de iDEAL QR code slechts eenmaal mag worden gebruikt of dat het een QR code betreft die meerdere malen gebruikt mag worden. | true/false |
| De datum en tijd waarop de QR code vervalt en dus niet meer kan worden gebruikt voor een iDEAL transactie (UTC) | DT yyyy-MM-dd HH:mm |
| De naam van de begunstigde van de iDEAL QR transactie die op de pagina met betaalgegevens te zien is. | AN..100 |
| De Merchant sub-id zoals ook gebruikt voor de iDEAL transactie. 0 wanneer geen sub-id aanwezig is. | N..Max 6 |
| De referentie die door de Merchant ook wordt meegegeven in het iDEAL protocol. | ANS..Max 35 |
| In dit veld wordt door Merchant aangegeven wat de grootte van de QR code is in pixels. De waarde kan tussen de 100-2000 px liggen. | N..100-2000 |
Velden van de iDEAL QR Generate API call.
4.2 iDEAL QR Generate Response
De Merchant ontvangt de Generate Response als antwoord op de Generate API call in een http 200 OK bericht met in de body de JSON data elementen. Dit bericht bevat de verwijzing naar de gegenereerde QR-code en bevat een uniek QR-code ID.
De tabel hieronder toont alle velden die voorkomen in de Generate Response en hun formaat.
Naam | Omschrijving | Formaat |
|---|---|---|
| De URL waar de QR code .png file staat in het gespecificeerde formaat die door de Merchant daar kan worden opgehaald. | AN |
| Een unieke random code waarmee de QR code en de gekoppelde betaalgegevens kunnen worden geïdentificeerd. | AN..36 |
Velden van de iDEAL QR Generate response.
De iDEAL QR-code kan vervolgens door de Merchant gebruikt worden, maar mag niet gewijzigd worden. Daarnaast dienen, ten behoeve van het tonen van de QR-code, de richtlijnen te worden gevolgd zoals gespecifieerd door uw Acquirer in de iDEAL QR Richtlijnen.
5. Transactie verzoek na scannen iDEAL QR code – iDEAL QR Transaction protocol
Nadat de Consument de iDEAL QR code heeft gescand met de iDEAL App ontvangt zij de transactiegegevens in haar scherm. De Consument wijzigt vervolgens eventueel het bedrag waarna ze de iDEAL QR transactie bevestigt. Met deze bevestiging wordt een API call iDEAL QR Transaction verstuurd vanuit de iDEAL QR backend naar de Merchant. Deze API call dient als een trigger voor het opstarten van het iDEAL transactieprotocol vanuit de Merchant naar de Acquirer. De IssuerauthenticatieURL, die de Merchant vervolgens ontvangt vanuit de Issuer (via de Acquirer), dient door de Merchant als API response te worden teruggestuurd naar de iDEAL QR back-end.
5.1 iDEAL QR Transaction API call
Als resultaat van een door de Consument bevestigde iDEAL QR transactie , stuurt de QR back-end een iDEAL QR Transaction API call naar de Merchant. De iDEAL QR Transaction API call bestaat uit een JSON bericht dat via een HTTP POST request naar de door de Merchant vooraf opgegeven API URL wordt gestuurd.
De tabel hieronder toont alle velden die voorkomen in de iDEAL QR Transaction API call en hun formaat:
Naam | Omschrijving | Formaat |
|---|---|---|
merchant_id | Het MerchantID zoals doorgegeven tijdens de Merchant registratie en zoals opgeslagen op de QR back-end | PN..9 |
qr_id | Een unieke random code waarmee de QR code en de gekoppelde betaalgegevens kunnen worden geïdentificeerd. | AN..36 |
issuer_id | Dit is het iDEAL IssuerID dat overeenkomt met de bank die de consument in de iDEAL app heeft opgegeven als voorkeursbank voor het betalen van deze specifieke iDEAL QR transactie. | ANS..max 11 |
amount | Het bedrag dat door de consument is bevestigd na het scannen van de QR code. Dit bedrag dient als euro bedrag te worden opgenomen in de iDEAL transaction request. Er wordt een punt (.) gebruikt als decimaalteken | DEC |
purchase_id | Dit is het purchaseID dat door de Merchant is meegegeven bij het genereren van de QR code en dus ook als kenmerk is getoond aan de consument na het scannen van de QR code. Wanneer meegegeven dient deze Purchase ID ook gebruikt te worden in het iDEAL Transaction Request. |
|
merchant_sub_id | De Merchant sub-id zoals ook gebruikt voor de iDEAL transactie. | N..max 6 |
description | De omschrijving die bij de QR code generatie is meegegeven en die de consument als omschrijving in zijn scherm heeft ontvangen en bevestigd. | AN..max 35 |
Velden van de iDEAL QR Transaction API call.
Wanneer de Merchant deze iDEAL QR Transaction API call ontvangt, dient zij automatisch een iDEAL transaction request naar zijn Acquirer te initiëren. In dit iDEAL TransactionRequest (bericht B) dienen de ontvangen velden uit de iDEAL QR Transaction API call te worden overgenomen. De overige benodigde velden voor het TransactionRequest zoals de MerchantReturnURL dient de Merchant hieraan toe te voegen.
5.2 iDEAL QR Transaction Response
Na het versturen van de hierboven genoemde iDEAL TransactionRequest (B) ontvangt de Merchant van de Acquirer het TransactionResponse bericht terug (B'). De Merchant dient deze te kunnen herkennen als behorende bij een iDEAL QR transactie en automatisch een response te sturen op de bijbehorende API call iDEAL QR Transaction. Deze iDEAL QR Transaction API response is een JSON bericht dat via een HTTP 200 OK response naar de QR back-end wordt teruggestuurd.
De tabel hieronder toont de velden die de Merchant dient mee te geven in het iDEAL QR Transaction API response en hun formaat:
Naam | Omschrijving | Formaat |
|---|---|---|
issuer_authentication_url | Dit is IssuerAuthenticationURL van de Issuing bank zoals teruggekregen in de iDEAL transaction response bericht van de Acquirer. | AN..max 512 |
transaction_id | Het iDEAL TransactionID zoals door de Acquiring bank is teruggegeven in het transaction response bericht. | PN..16 |
Velden van de iDEAL QR Transaction response.
Na het afgeven van de iDEAL QR transaction response aan de iDEAL QR back-end zal de Consument worden doorgestuurd naar de vooraf gekozen Issuer met behulp van de IssuerAuthenticationURL. De Consument zal in zijn eigen Issuing-bank mobiel bankieren omgeving de iDEAL transactie behorende bij de gescande iDEAL QR-code bevestigen en afronden. Na afronding zal de Consument terug worden gestuurd naar de MerchantReturnURL, zoals meegegeven door de Merchant in de iDEAL TransactionRequest. De Merchant dient hier het normale iDEAL protocol te volgen en dus na het terug ontvangen van de Consument de status op te vragen en te tonen aan de Consument in de pagina van de opgegeven MerchantReturnURL.
6. Status na afronding - iDEAL QR Status protocol
Nadat de Consument op de MerchantReturnURL is terecht gekomen is de iDEAL transactie afgerond. Wel dient de finale status van de iDEAL transactie, die behoort bij de iDEAL QR-code nog te worden doorgegeven en geregistreerd op de iDEAL QR back-end. Hiertoe zal de iDEAL QR back-end middels een API call de status opvragen bij de Merchant. Deze API call kan door twee elementen worden getriggerd:
- Tijd: Elke 30 minuten vanaf het moment dat de iDEAL QR transaction response is ontvangen door de iDEAL QR back-end van de Merchant en alleen als van deze transactie nog geen iDEAL transactie eindstatus is ontvangen
- Nieuwe scan one-off QR code: Wanneer een one-off QR code, waarvoor al een iDEAL QR transaction request is verstuurd, opnieuw wordt gescand en alleen als van deze transactie nog geen iDEAL transactie eindstatus is ontvangen
6.1 iDEAL QR Status API call
Getriggerd door één van de twee hierboven genoemde elementen stuurt de iDEAL QR back-end een Status API call naar de Merchant. De Status API call bestaat uit een JSON bericht dat via een HTTP POST request naar de door de Merchant vooraf opgegeven API URL wordt gestuurd.
De tabel hieronder toont de velden in het Status API call en hun formaat:
Naam | Omschrijving | Formaat |
|---|---|---|
merchant_id | De MerchantID zoals op de iDEAL QR back-end gekoppeld aan het TransactionID | PN..9 |
merchant_sub_id | De Merchant sub-id zoals op de iDEAL QR back-end gekoppeld aan het TransactionID | N..max 6 |
transaction_id | Het iDEAL TransactionID zoals deze bij de iDEAL QR back-end bekend is | PN..16 |
Velden van de iDEAL QR Status API call.
6.2 iDEAL QR Status response
Als response op de Status API call geeft de Merchant, wanneer de eindstatus bij de Merchant bekend is, de iDEAL status door aan de iDEAL QR back-end. Wanneer de eindstatus nog niet bekend is, dient de Merchant de status "Open" terug te geven. De Status API response bestaat uit een JSON bericht dat via een HTTP 200 OK response naar de QR back-end wordt teruggestuurd.
De tabel hieronder toont de velden in het Status API call en hun formaat:
Naam | Omschrijving | Formaat |
|---|---|---|
ideal_status | De iDEAL status behorende bij de transaction-id zoals genoemd in de Status API call. Wanneer de status (nog) niet bekend is dient de Merchant hier de status "Open" mee te geven. | AN..max 15 |
Velden van de iDEAL QR Status response.
One-off iDEAL QR codes waarvan de QR back-end de iDEAL status Success heeft ontvangen, zullen worden afgesloten en kunnen niet opnieuw worden gescand.
7. Error responses vanuit back-end
In geval van een error (bijv. validatie, connectie of authenticatie error), wordt ter communicatie over de error vanuit de back-end een HTTP 4xx of 5xx response met de error code en error message in de body (als mogelijk) verstuurd.
7.1 Error Response Message
Het body van het bericht bevat de elementen "status", met de gebruikte HTTP status code, "code" met de specific iDEAL QR error code en "message" met het error message dat correspondeert met de iDEAL QR error code.
Velden in de iDEAL QR Error response:
Naam | Description | Format |
|---|---|---|
| HTTP status code voor deze error. | N. 3 |
| De code die correspondeert met een zeker type error. | N. 4 |
| Een omschrijving van de error. | AN. |
7.2 Error Codes
De volgende Error codeszijn momenteel beschikbaar en worden gebruikt:
Error Code | Error message | Examples of providing error | HTTP Status Code |
|---|---|---|---|
1001 | Error while saving to the database | General internal error within back-end while trying to process request | 500 |
1002 | Record was not found in the database | iDEAL QR ID not found in database(404); MerchantID not found in database (400) | 404; 400 |
1003 | HTTP verb is not allowed | In case other HTTP verb is used than POST | 405 |
1004 | HTTP request was invalid | General error for incorrect elements in HTTP | 400 |
1005 | HTTP request validation failed | Merchant_token not recognized; | 400 |
1006 | HTTP request not found | Response not matchable with HTTP request | 404 |
| 9998 | Technical Error | Internal Technical Error | 500 |
| 9999 | Unknown | Unknown error, shall be returned if any unexpected exception is thrown | 500 |
Zie HTTP Status Codes kolom voor de HTTP status code is die bij de error code wordt gebruikt.
8. Verwerkingssnelheid tbv iDEAL QR Transaction protocol
Wanneer de Consument de QR transactie bevestigt, dient de redirect naar de Issuer, met het oog op de gebruikerservaring, niet te lang op zich te laten wachten. Er wordt daarom een streeftijd gespecificeerd en een time-out ten behoeve van het tussenliggende protocol tussen de Merchant en de iDEAL QR back-end. De time-out wordt gezet op 10 seconden voor de Consument. Dat wil zeggen, als de Consument na 10 seconden na het bevestigen van de transactie bij de Merchant niet is doorgeleid naar haar Issuer, wordt een foutmelding getoond en zal de iDEAL QR code (in geval van one-off) te allen tijde opnieuw door de Consument kunnen worden gescand. De eventueel gestarte iDEAL transactie zal dan verlopen.
De QR back-end zal daarom uitgaan van een time-out periode van 9,5 seconde tussen het versturen van de QR Transaction API call en de response daarop vanuit de Merchant. Echter, er zal hiervoor een streeftijd worden gehanteerd van 3.0 seconden.
Communicatie iDEAL QR Transaction API | Streeftijd (seconden) | Time-out (seconden) |
|---|---|---|
API call van QR back-end → API response Merchant | 3.0 | 9.5 |
Richtlijnen verwerkingssnelheid iDEAL QR Transaction protocol
9. Beveiliging iDEAL QR
Ten behoeve van de beveiliging van de dataverbinding en het berichtenverkeer tussen Merchant en de iDEAL QR back-end zijn de volgende elementen en maatregelen voorzien:
Merchant Token
Bij de registratie ontvangt de Merchant een unieke Merchant token. Ten behoeve van identificatie en authenticatie dient de Merchant in de Generate QR API call berichten, die ze verstuurt naar de iDEAL QR back-end ten behoeve van het genereren van iDEAL QR-codes, dit Merchant token in een apart veld mee te geven. Op basis van dit token zal de Merchant worden geauthentiseerd door de iDEAL QR back-end. De Merchant dient dit Merchant token te alle tijden geheim te houden. Wanneer de token is gecompromitteerd dient de Merchant hierover meteen contact op te nemen met haar Acquirer.
Certificaat ten behoeve van TLS verbinding
Voor de communicatie tussen de Merchant en de iDEAL QR back-end is een beveiligde TLS verbinding benodigd. De Merchant dient ten behoeve van deze TLS dataverbinding met de iDEAL QR back-end in het bezit te zijn en gebruik te maken van een geldig TLS/SSL certificaat, uitgegeven door een willekeurige trusted Certificate Authority. Ook de iDEAL QR back-end zal van een dergelijk TLS certificaat gebruik maken om zich te authentiseren en de TLS verbinding op te zetten. De public keys dienen niet voorafgaand te worden uitgewisseld en/of gepind. Ten behoeve van het berichtenverkeer tussen de Merchant en de IDEAL QR back-end dient minimaal TLS versie 1.1 ondersteund te worden.
Signing secret key
Bij de registratie zal een unieke secret signing key worden uitgewisseld door de iDEAL QR backend met de Merchant. De iDEAL QR back-end ondertekent al zijn API call and response berichten middels HMAC (SHA256). De body van het JSON bericht en de verstrekte secret key worden gebruikt als input variabelen voor de HMAC functie. De resulterende HMAC hash wordt als signature geplaatst in de bericht header onder header naam: x-ideal-qr-hash. De merchant validateert deze signature middels dezelfde HMAC functie en input variabelen.
De secret key dient geheim te worden gehouden ten alle tijde. Wanneer de key wordt gecompromiteerd, dient de Merchant onmiddelijk contact op te nemen met de Acquirer.
HMAC Voorbeeld (ter validatie van implementatie):
Message body: {"qr_id":"1234test","qr_url": "https://qrcode.ideal.nl/1234test"}
Secret key: key123
Resulting HMAC signature hash: ae36cd6aeea48c050c3cf80f8bc25170f37fc2346d1ee294a8b815a2cca9c736
APPENDIX: Voorbeeldberichten IDEAL QR (Body)
iDEAL QR Generate API call
POST /ideal-qr/v1.0/generate { "merchant_token": "784aea4c-e36c-4a4b-b164-f9818aaeaf5c", "merchant_sub_id": 5, "amount": 24.95, "amount_changeable": true, "amount_max": 30.00, "amount_min": 20.00, "description": "Product Y", "one_off": true, "expiration": "2016-05-14 00:00", "beneficiary": "Organisatie X", "purchase_id": "PO1234567", "size": 1000 }
iDEAL QR Generate response
{"qr_id": "5d6b159b-41ab-48eb-b379-da18ddea06dc","qr_url": https://qrcode.ideal.nl/codes/5d6b159b-41ab-48eb-b379-da18ddea06d?size=1000}iDEAL QR Transaction API call
POST [https://api.organizationx.nl/ideal-qr/transaction]{"merchant_id": 100298765,"qr_id": "5d6b159b-41ab-48eb-b379-da18ddea06dc","issuer_id": "NLABC123","merchant_sub_id": 5,"amount": 10.00,"purchase_id": "PO1234567","description": "Product Y",}
iDEAL QR Transaction response
{ "issuer_authentication_url": "https://www.bankx.nl/nl/ideal- betalen/index.html?randomizedstring=123456789&trxid=002000123456789", "transaction_id": "002000123456789", }
iDEAL QR Status API call
POST [https://api.organizationx.nl/ideal-qr/status] { "merchant_id": 100298765, "merchant_sub_id": 5, "transaction_id": "002000123456789"}
iDEAL QR Status response
{ "ideal_status": "success"}
{"status": 405,"code": 1003,"message": "HTTP verb is not allowed"}
Copyright © Currence iDEAL B.V. All rights reserved.