| Excerpt |
|---|
Version: 1.5 |
...
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 centrale betreffende iDEAL QR back-end. Na acceptatie van zijn 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 deelname aan het QR protocolkunnen 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 verstuurd. |
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 | Telefoon nummer Telefoonnummer van de contactpersoon |
Na de registratie ontvangt de Merchant van de Acquiring partij:
Data-element | Omschrijving |
|---|---|
Merchant Token | Een geheim identificatie nummer 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 1.8 9 over veiligheid. |
| Note | ||
|---|---|---|
| ||
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. |
...
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 protocol 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 1.8 9 voor meer informatie over beveiliging en de signing signature.
...
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 in de app. 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 in de app 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 app 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 |
...
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-codes code en bevat een uniek QR-code ID.
De tabel hieronder toont alle velden die voorkomen in de Generate Response en hun formaat.
...
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 handboek huisstijlRichtlijnen.
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 en/of zijn/haar vooraf ingestelde voorkeursbank, 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.
...
Als resultaat van een door de Consument in de iDEAL app 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 in de iDEAL App na het scannen van de QR code. Alleen dit 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 in de iDEAL App 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 |
...
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:
...
Na het afgeven van de iDEAL QR transaction response aan de iDEAL QR back-end zal de Consument vanuit de iDEAL App 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.
...
In geval van een error (bijv. validatie, connectie of authenticatie error), wordt ter communicatie ofver 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.
...
8. Verwerkingssnelheid tbv iDEAL QR Transaction protocol
Wanneer de Consument in de app 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, zal de app wordt een foutmelding geven 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.
...
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)
...