| Insert excerpt | ||||||
|---|---|---|---|---|---|---|
|
...
After registration, the Merchant will receive:
Data element | Description |
|---|---|
Merchant Token | A secret identification number specific to the Merchant which the iDEAL QR back-end uses to identify and authenticate the Merchant. The Merchant can use this token to have iDEAL QR codes generated by the iDEAL QR back-end. |
API URLs QR backend | The API URLs of the Merchant to which the QR back-end sends its requests. |
Secret signing key | A secret symmetric key with which the iDEAL QR back-end signs all their messages and with which the Merchant can authenticate the incoming messages. See paragraph |
...
To generate an iDEAL QR code, the Merchant must perform a Generate API call. This consists of a JSON message that is sent to the QR back-end as the body of an HTTP POST request.
| Note |
|---|
Please note that the API URL for the Generate API calls is specific per Acquirer and will be communicated to as part of the registration process. Also see chapter 2. |
The table below shows the fields in the Generate API call and the required format.
Name | Description | Format |
|---|---|---|
| This is the ID that the Merchant receives for onboarding at the QR back-end. It identifies and authenticates the Merchant at the QR back-end. | AN..36 |
| The pre-entered amount for the specific QR code. A full stop (.) is used to show the decimal point. Amount cannot be 0 (as iDEAL transactions of 0 are not possible) | DEC (12.2) |
| This field indicates whether the Consumer can edit the amount in the app. Enter 'false' when the amount must not be fixed and 'true' when the amount must be editable by the user. Please note that for fixed amounts, the amount must be entered and it cannot be 0. | true/false |
| In this field a maximum amount can be provided if the amount is not fixed. It must be larger than 0 and larger than "amount". | DEC (12.2) |
| In this field a mimimum amount can be provided if the amount is not fixed. It must be larger than 0 and smaller than "amount". | DEC (12.2) |
| The payment description shown in the app and specified in the iDEAL messages protocol. | AN..max 35 |
| This field indicates whether the iDEAL QR code may be used only once or whether it can be used multiple times. | true/false |
| The date and time at which the QR code expires and can no longer be used for iDEAL transactions (UTC). | DT yyyy-MM-dd HH:mm |
| The name of the recipient of the iDEAL QR transaction displayed in the app. | AN..100 |
| The Merchant subID as also used for the iDEAL transaction. Use 0 when no sub-id is applicable. | N..Max 6 |
| The reference also provided by the Merchant in the iDEAL protocol. | ANS..Max 35 |
| In this field, the Merchant indicates the size of the QR code in pixels. The value must be between 100 and 2000 px. | N..100-2000 |
...
When the Consumer confirms the iDEAL QR transaction in the iDEAL app, the QR back-end sends an iDEAL QR Transaction API call to the Merchant. This consists of a JSON message that the Merchant sends to the earlier specified API URL by means of an HTTP POST request.
The table below shows all the fields in the iDEAL QR Transaction API call and the required format.
Name | Description | Format |
|---|---|---|
| The MerchantID provided when the Merchant registers, as stored at the QR back-end. | PN..9 |
| A unique random code used to identify the QR code and the associated payment details. | AN..36 |
| The iDEAL IssuerID that corresponds to the preferred bank specified by the Consumer in the iDEAL app for the payment of this specific iDEAL QR transaction. | ANS..Max 11 |
| The amount confirmed by the consumer in the iDEAL App after scanning the QR code. Only this amount must be included (in €) in the iDEAL transaction request. A full stop (.) is used for the decimal point. | DEC |
| This is the PurchaseID issued by the Merchant when the QR code is generated, and also displayed to the Consumer as a reference in the iDEAL App after the QR code has been scanned. Once issued, this | ANS..Max 35 |
| The Merchant subID as also used for the iDEAL transaction. Use 0 when no sub-id is applicable. | N..Max 6 |
| The description provided when the QR code was generated and that the Consumer has received and confirmed. | AN..Max 35 |
...
After sending the iDEAL TransactionRequest described above (message B), the Merchant
receives a TransactionResponse message back from the Acquirer (B'). The Merchant must be able to recognize that this response relates to an iDEAL QR transaction and automatically send a response to the corresponding iDEAL QR Transaction API call. The iDEAL QR Transaction API response consists of a JSON message sent to the QR back-end by means of an HTTP 200 OK response.
The table below shows the fields that the Merchant must include in the iDEAL QR Transaction API response and the required format:
Name | Description | Format |
|---|---|---|
| The IssuerAuthenticationURL of the Issuing Bank, received in the iDEAL transaction response message from the Acquirer. | AN..max 512 |
| The iDEAL TransactionID provided by the Acquiring Bank in the transaction response message. | PN..16 |
...
Name | Description | Format |
|---|---|---|
| The MerchantID associated with the iDEAL QR TransactionID at the iDEAL QR back-end. | PN..9 |
| The Merchant SubID associated with the iDEAL QR TransactionID at the iDEAL QR back-end. | N..Max 6 |
| The iDEAL TransactionID known to the iDEAL QR back-end. | PN..16 |
...
HMAC Example (to validate implementation):
Message body: {"qr_id":"1234test","qr_url": "https://qrcode.ideal.nl/1234test"}
Secret key: key123
Resulting HMAC signature hash: ae36cd6aeea48c050c3cf80f8bc25170f37fc2346d1ee294a8b815a2cca9c736
...
APPENDIX: Example iDEAL QR messages (Body)
...