iDIN QR - Merchant/DISP Implementation Guidelines
- Currence
- Roland Thijssen
Version: 0.3 - Jan 2020
Contents
Versions
1. Message format
For communication to and from the iDIN QR back-end, a RESTful API protocol is used. These messages are HTTP POST and HTTP response messages with JSON data elements in the body. See below an example of a message used for the GENERATE API call.
All messages from the iDIN QR back-end to the Merchant also include a signature hash in the header of the message. Its purpose is to allow the Merchant to authenticate and validate the content of the messages. Please note that this signature hash is not required the other way around! Messages from the Merchant to the back-end are not signed with the secret key.
See below an example of a message used for the iDIN QR Generate API Call (from the Merchant to the iDIN QR back-end).
Example of an iDIN QR Generate API call (Merchant to iDIN QR back-end).
Header |
|
|---|---|
Body |
|
Example of an iDIN QR Generate API response (iDIN QR back-end to Merchant). For more message examples see Appendix
Header |
|
|---|---|
Body |
|
2. Merchant Registration and Onboarding
In order to be able to use iDIN QR, the Merchant must have an iDIN contract in place with one of the iDIN acquiring parties. Without an iDIN connection, it is not possible to onboard on iDIN QR. The Merchant contacts its iDIN acquirer in order to register for iDIN QR. After this registration has been accepted, the Merchant can connect to the iDIN QR back-end and generate iDIN QR codes.
The following information must at least be registered in the iDIN QR back-end before the Merchant can use iDIN QR.
Elements to be received from Merchant/CPSP for registration at an iDIN QR back-end:
Data element | Description |
|---|---|
MerchantID | The iDIN MerchantID of Merchant, issued by the iDIN Acquirer. |
LegalName | The legal name of the Merchant, as registered with the Acquirer. |
Merchant API URLs | The URLs which the iDIN QR back-end uses to communicate to the Merchant. |
Contact name | Name of the person who can be contacted in the event of operational problems. |
Contact email | Email address of the contact person. |
Contact phone | Telephone number of the contact person. |
After registration, the Merchant will receive from the iDIN QR back-end directly or via the Acquirer:
Data elements provided to a Merchant after successful registration for iDIN QR:
Data element | Description |
|---|---|
Merchant Token | A secret identification number specific to the Merchant which the iDIN QR back-end uses to identify and authenticate the Merchant. The Merchant must use this token to authenticate itself when generating iDIN QR code at the iDIN QR back-end. |
API URLs QR back-end | The API URL that the Merchant uses to communicate to the QR back-end for iDIN QR Generate API calls. |
Secret signing key | A secret symmetric key, created by the iDIN QR back-end with which the iDIN QR back-end must sign all its messages. The Merchant should validate the signature in the messages that it receives from the iDIN QR back-end by function of HMAC-SHA256(message body, secret key). |
Please note that checking the validity of the Merchant ID and Legal Name are the responsibility of the iDIN acquirer.
3. Generating of iDIN QR codes
The iDIN QR back-end generates iDIN QR codes for Merchants. The steps to generate an iDIN QR code are:
The Merchant sends iDIN QR Generate API call to iDIN QR back-end;
The iDIN QR back-end registers transaction information and generates an iDIN QR code;
The iDIN QR back-end responds to the Merchant Generate API call with an URL that hosts the QR code;
The Merchant retrieves/makes use of the iDIN QR code at the specified URL.
To generate an iDIN QR code, the Merchant performs a Generate API call. This is a JSON message that is sent to the QR back-end as the body of an HTTP POST request. The table below shows the fields in the Generate API call and the required format.
In response to the Generate API call, the iDIN QR back-end sends a HTTP 200 OK message to the Merchant with the QR ID and the QR URL in the body.
Body Parameters
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. | string |
| The Merchant subID as also used for the iDIN transaction. Use 0 when no sub-id is applicable. | number |
| The date and time at which the iDIN QR code expires and can no longer be used to initiate iDIN transactions. (store in UTC) | string |
| In this field, the Merchant indicates the size of the QR code in pixels. The value must be between 100 and 2000 (pixels). | number |
| Indicate which iDIN Service ID is to be used for the iDIN transaction (e.g. 16384 for Login) | number |
| Used to be able to differentiate (e.g. for security measures) between use cases. Values are provided upon request | string |
Response Body Parameters
Name | Description | Format |
|---|---|---|
| A unique random code used to identify the QR code and the associated details. Format is UUID. Note: must be strict UUID; i.e. conform UUID RFC 4122. Version 4 must be used. | string |
| The URL at which the QR code .png file is located in the specified format and where this is available for collection by the Merchant. | string |
Example Request
POST https://qrcode.idin.nl/idin-qr/v1.0/generate
{"merchant_token": "784aea4c-e36c-4a4b-b164-f9818aaeaf5c","merchant_sub_id": 5,"expiration": "2019-10-28 00:00:00","size": 1000,"idin_service_id": 16384,"use_case": "00"}
Example Response 200
{"qr_id": "5d6b159b-41ab-48eb-b379-da18ddea06dc","qr_url":"https://qrcode.idin.nl/qrcode/8bc99532-bb2a-4002-8c9b-7c33010d9847.png"}
Example Request
POST https://qrcode.idin.nl/idin-qr/v1.0/generate
{"merchant_token": "784aea4c-e36c-4a4b-b164-f9818aaeaf5c","merchant_sub_id": 5,"expiration": "2019-10-28 00:00:00","size": 1000,"idin_service_id": 16384,"use_case": "00"}
Example Response 200
{"qr_id": "5d6b159b-41ab-48eb-b379-da18ddea06dc","qr_url": "https://qrcode.idin.nl/qrcode/8bc99532-bb2a-4002-8c9b-7c33010d9847.png"}
4. iDIN QR transaction API
After a user scans an iDIN QR code, the iDIN QR back-end sends an iDIN QR Transaction API call to the Merchant. The Merchant initiates the actual iDIN transaction based on this call. It consists of a HTTP POST with the necessary iDIN transaction elements in the body (JSON).
Following the standard iDIN protocol, the Merchant then sends an iDIN AcqTransactionRequest to its Acquiring bank, with which the actual iDIN transaction is initiated. In the response from its Acquiring bank the Merchant receives the IssuerAuthenticationURL, which it forwards to the iDIN QR back-end as a response to the iDIN QR Transaction API call (HTTP 200 OK response with body in JSON). The below table shows the elements that are included in these messages.
Body Parameters
Name | Description | Format |
|---|---|---|
| The iDIN IssuerID that corresponds to the preferred bank specified by the payee in the iDIN app for the payment of this specific iDIN QR transaction. | string |
| The MerchantID provided by the Merchant at registration, and stored at the QR back-end. | string |
| The Merchant SubID, which is also used for the iDIN transaction. | number |
| The ID from the QR code to which the confirmation belongs. | string |
| Defines the service ID to be used for the iDIN trx | number |
Response Body Parameters
Name | Description | Format |
|---|---|---|
| The IssuerAuthenticationURL of the Issuing Bank, received in the iDIN transaction response message from the Acquirer. | string |
| The iDIN TransactionID provided by the Acquiring Bank in the transaction response message of the standard iDIN protocol. | string |
Example Request
POST https://api.organizationx.nl/iDIN-qr/transaction
{"merchant_id": "100298765","qr_id": "5d6b159b-41ab-48eb-b379-da18ddea06dc","issuer_id": "NLABC123","merchant_sub_id": 5,"idin_service_id": 16384}
Example Response 200
{"issuer_authentication_url": "https://www.bankx.nl/nl/iDIN/index.html?randomizedstring=123456789&trxid=002000123456789","transaction_id": "002000123456789"}
5. Processing of Unhappy flows and Error Codes
In case of an error (e.g. validation, connection or authentication error) an HTTP 4xx or 5xx response with the error code and error message in the body is used (when possible) to communicate the error.
The body of the message contains the element "status" which provides the HTTP status code used, "code" which states the specific iDIN QR error code and the "message" which states the applicable error message that corresponds to the iDIN QR error code.
Fields in the iDIN QR Error response:
Name | Description | Format |
|---|---|---|
| HTTP status code used for this error. | number |
| The code that corresponds with a certain type of error. | number |
| A message is provided that explains the error. | string |
Below Error codes provide guidance on the handling of unhappy flows.
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 | iDIN 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 |
6. Security
To ensure the security of the data connection and message traffic between the Merchant and the iDIN QR back-end, the following elements and measures are in place:
6.1 Merchant Token
Upon registering, the Merchant receives a unique Merchant Token. The Merchant must include this token for identification and authentication purposes in a separate field in the Generate QR API call messages that it sends to the iDIN QR back-end to generate iDIN QR codes. The iDIN QR back-end will validate the Merchant token field to authenticate the Merchant. The Token must be kept secure by the Merchant.
6.2 Certificate for TLS connection
A secure TLS connection is required for communication between the Merchant and the iDIN QR back-end. The Merchant must be in possession of and make use of a valid TLS/SSL certificate, issued by a trusted CA, in order to establish this TLS data connection with the iDIN QR back-end. The iDIN QR back-end will also use such a TLS certificate. Both sides will validate the SSL certificates via mutual authentication. The public keys must not be exchanged or pinned in advance. TLS version 1.1 or above must be supported for the exchange of messages between the Merchant and the iDIN QR back-end. At least 2048-bit for RSA.
6.3 Signing secret key
Upon registration, a unique secret signing key will be exchanged with the Merchant by the iDIN QR back-end. This secret key should be at least 128 bits and should be generated by a strong random-number-generator. The iDIN QR back-end will sign all its API call and response messages through HMAC (SHA256). The body of the JSON message and the provided secret key are used as input variables for the HMAC function. The resulting HMAC hash is placed as signature in the message header under header name x-iDIN-qr-hash. The merchant validates this signature through the same HMAC function and input variables.
HMAC Example (to validate implementation):
Message body: {"qr_id":"1234test","qr_url": "https://qrcode.iDIN.nl/1234test"}
Secret key: 83806dea0cffe9b5abf3c47c57976668bce32d3d497ee7b33fe99979bcd23710
Resulting HMAC signature hash: 43febdba2ec39ad843603a3c4fd387d9a147d44d53f8e1e43f8383d9f3a857ba
Note: The secret key as well as the merchant token must remain secret at all times. In the event that the key and/or token is compromised, the Merchant must contact the Acquirer immediately.
6.4 IP whitelisting
If specifically required by the Merchant, the back-end is able to enable whitelisting of one or several IP addresses/range associated with a Merchant token. An enabled whitelist for a given Merchant token will only allow connection with the whitelisted ip-addresses/ranges
6.5 Use Case
Some use cases have extra security measurements in place to mitigate security risks (e.g. shortened possible expiry, set maximum number of scans possible etc.) It is therefore important that the appropriate value in the use_case field is provided in the Generate API call from the Merchant to the Back-end.
Appendix A: Example iDIN QR messages
GENERATE API
Example Request
POST https://qrcode.idin.nl/idin-qr/v1.0/generate
{"merchant_token": "784aea4c-e36c-4a4b-b164-f9818aaeaf5c","merchant_sub_id": 5,"expiration": "2017-05-14 00:00:00","size": 1000,"idin_service_id": 16384,"use_case": "00"}
Example Response 200
{"qr_id": "5d6b159b-41ab-48eb-b379-da18ddea06dc","qr_url": "https://qrcode.idin.nl/qrcode/8bc99532-bb2a-4002-8c9b-7c33010d9847.png"}
TRANSACTION API
Example Request
POST https://api.organizationx.nl/iDIN-qr/transaction
{"merchant_id": "100298765","qr_id": "5d6b159b-41ab-48eb-b379-da18ddea06dc","issuer_id": "NLABC123","merchant_sub_id": 5,"idin_service_id": 16384}
Example Response 200
{"issuer_authentication_url": "https://www.bankx.nl/nl/iDIN/index.html?randomizedstring=123456789&trxid=002000123456789","transaction_id": "002000123456789"}
Error response (example)
|
|