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:

  1. Create a new iDEAL QR code and present it to your consumers.. (Create Method)
  2. The consumer scans the QR code with their banking app.
  3. The consumer is presented with the transaction details and, if so configured, can change the payment amount.
  4. The consumer confirms the transaction with their banking app and your system is notified.
  5. 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 12a34bc5de67f8g9012345678

RESTful 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/qr

With 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
minAmount 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
maxAmount 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
2020-10-21 15:38:41
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

Key Value
amount Amount too low, the minimum is set to: 49 - 25 given.
description Description cannot be blank.

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 in case of errors if the parameters are correctly taken from the documentation. If this seems to be the case. Please contact DigiWallet and mention the error message.

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:
  • Active
  • Expired
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

Key Value
qrCodeID There is no QR code for this ID.

Example raw response

{"status":1,"message":"Validation failed","errors":{"qrCodeID":["There is no QR code for this ID."]}}

Check in case of errors if the parameters are correctly taken from the documentation. If this seems to be the case. Please contact DigiWallet and mention the error message.

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:
  • Expired

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

Key Value
qrCodeID There is no QR code for this ID.

Example raw response

{"status":1,"message":"Validation failed","errors":{"qrCodeID":["There is no QR code for this ID."]}}

Check in case of errors if the parameters are correctly taken from the documentation. If this seems to be the case. Please contact DigiWallet and mention the error message.