iDEAL QR API
With the REST API for iDEAL QR, you can quickly generate QR codes that a consumer can scan to automatically start up an iDEAL transaction.
The iDEAL QR flow in short:
- Create a new iDEAL QR code and present it to your consumers.. (Create Method)
- The consumer scans the QR code with their banking app.
- The consumer is presented with the transaction details and, if so configured, can change the payment amount.
- The consumer confirms the transaction with their banking app and your system is notified.
- You can terminate the iDEAL QR code at any time. (Terminate Method)
HTTP Bearer Authentication
This API requires HTTP Bearer authentication (Read more...) This means your requests to this API must always be accompanied by an HTTP header carrying your organization's API key to be accepted.
You can find your organization's unique API token in your Organization Dashboard.
An example of the HTTP header is as follows:
Authorization: Bearer 12a34bc5de67f8g9012345678RESTful API
This is a RESTful API. This means the API follows the RESTful format for web services (Read more...)
The response format for these API's is in (JSON).
A typical response will be a JSON-encoded array with a status integer to indicate whether the call was successful or not, and a message string with a description of what happened.
Beyond these standard elements, an API can return API-specific information. e.g. transactionID integer for the creation of a transaction. Or a nested errors array
providing detailed validation errors.
The HTTP response codes of the RESTful API's follow the below logic:
| HTTP Status Code | Used in response to |
|---|---|
| 200 (Success) | A successfully processed request that also returns information |
| 201 (Created) | A successfully processed creation request |
| 202 (Accepted) | A successfully accepted job request |
| 400 (Bad Request) | Bad input parameters / validation errors |
| 401 (Unauthorized) | Bad credentials |
| 404 (Not Found) | Resource could not be found |
| 405 (Method Not Allowed) | Method is unsupported in the API |
| 500 (Internal Server Error) | A problem occurred at DigiWallet's servers |
Create Method
Create new iDEAL QR code
To create a new iDEAL QR code, call the following API through HTTP POST.
https://api.digiwallet.nl/ideal/qrWith the following parameters (* = required):
| Variable | Explanation | Example |
|---|---|---|
| outletID* | The ID of the outlet on which you want to register the QR code. | 12345 |
| amount* | The amount of the transactions created through scanning the QR code. | 5000 |
| oneoff |
Whether or not this QR code is a one-off or reusable. Defaults to 0.
|
1 |
| amountChangeable |
Whether or not the consumer is allowed to change the payment amount. Defaults to 0.
|
1 |
| amountMin |
The minimum transaction amount that a consumer can choose in case amountChangeable is set to 1.
Can be left blank if amountChangeable is set to 0.
|
2500 |
| amountMax |
The maximum transaction amount that a consumer can choose in case amountChangeable is set to 1.
Can be left blank if amountChangeable is set to 0.
|
7500 |
| description* | Description for the consumer's bank statement. | Donation to the orphanage |
| expiration* |
Date and time in the future on which the QR code will expire. Format: YYYY-MM-DD
HH:MM:SS
|
2024-09-24 06:02:09 |
| size* |
The size in pixels of the QR code image. This value is used for both the width and the height. |
500 |
| returnURL* |
The location where your consumer will be returned to after completing the transaction. The parameters appended to this URL follow the same format as the regular (iDEAL API). |
https://www.myshop.nl/thankYouPage |
| cancelURL |
The location where your consumer will be returned to when they cancel the transaction. The parameters appended to this URL follow the same format as the regular (iDEAL API). If left blank, the returnURL will be used in place of the cancelURL. |
https://www.myshop.nl/cancelPage |
| reportURL* |
The server handler that is called when the consumer completes the transaction. This request is performed by means of HTTP POST.The parameters appended to this URL follow the same format as the regular (iDEAL API). Please utilize the iDEAL API Check Method to verify the authenticity of the reportURL callback. |
https://www.myshop.nl/reportTransaction |
You will then get a JSON-encoded array response with the following content:
| Key | Value |
|---|---|
| status | 0 |
| message | QR code successfully created |
| qrCodeID | ID of the created QR code
|
| qrCodeURL | URL to the QR code image
|
Example raw response
{"status":0,"message":"QR code successfully created","qrCodeID":12345,"qrCodeURL":"https://qr2.ideal.nl/ideal-qr/qr/get/5693727d-c230-4b27-856b-2db8902943ab"}
You can now save the qrCodeID
and the qrCodeURL
in your database and provide the QR code to your consumer(s).
In case of one or more errors, you will get a JSON-encoded array response with the following content:
| Key | Value | ||||||
|---|---|---|---|---|---|---|---|
| status | 1 | ||||||
| message | Validation failed | ||||||
| errors |
Nested JSON-encoded array of validation errors
Example
|
Example raw response
{"status":1,"message":"Validation failed","errors":{"initialAmount":["Amount too low, the minimum is set to: 49 - 25 given."],"description":["Description cannot be blank."]}}
Check Method Check QR code
To check the status of the QR code, call the following API through HTTP GET.
https://api.digiwallet.nl/ideal/qr/<outletID>/<qrCodeID>The query string parameters are defined as follows (* = required):
| Variable | Explanation | Example |
|---|---|---|
| outletID* | The ID of the outlet on which the QR code was registered. | 39995534 |
| qrCodeID* | The ID of the QR code. | 12345678 |
You will then get a JSON-encoded array response with the following content:
| Key | Value |
|---|---|
| status | 0 |
| message | QR code successfully checked |
| qrCodeStatus |
Current status of the QR code, options as follows:
|
| qrCodeURL | The URL of the QR code image. |
Example raw response
{"status":0,"message":"QR code successfully checked","qrCodeStatus":"Active","qrCodeURL":"https://qr2.ideal.nl/ideal-qr/qr/get/5693727d-c230-4b27-856b-2db8902943ab"}In case of one or more errors, you will get a JSON-encoded array response with the following content:
| Key | Value | ||||
|---|---|---|---|---|---|
| status | 1 | ||||
| message | Validation failed | ||||
| errors |
Nested JSON-encoded array of validation errors
Example
|
Example raw response
{"status":1,"message":"Validation failed","errors":{"qrCodeID":["There is no QR code for this ID."]}}
Terminate Method Terminate QR code
To terminate an active QR code early, call the following API through HTTP DELETE.
https://api.digiwallet.nl/ideal/qr/<outletID>/<qrCodeID>The query string parameters are defined as follows (* = required):
| Variable | Explanation | Example |
|---|---|---|
| outletID* | The ID of the outlet on which the QR code was registered. | 39995534 |
| qrCodeID* | The ID of the QR code. | 12345678 |
You will then get a JSON-encoded array response with the following content:
| Key | Value |
|---|---|
| status | 0 |
| message | QR code successfully terminated |
| qrCodeStatus |
New status of the QR code, options as follows:
|
Example raw response
{"status":0,"message":"QR code successfully terminated","qrCodeStatus":"Expired"}In case of one or more errors, you will get a JSON-encoded array response with the following content:
| Key | Value | ||||
|---|---|---|---|---|---|
| status | 1 | ||||
| message | Validation failed | ||||
| errors |
Nested JSON-encoded array of validation errors
Example
|
Example raw response
{"status":1,"message":"Validation failed","errors":{"qrCodeID":["There is no QR code for this ID."]}}