Creating an iDEAL QR request

The following details can be specified when creating a new iDEAL QR request:

  • amount - The pre-entered amount for the specific QR code.
  • amount_changeable - 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.
  • amount_max - 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”. – optional
  • amount_min - 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”. – optional
  • description - The payment description shown in the app and specified in the iDEAL messages protocol.
  • one_off - This field indicates whether the iDEAL QR code may be used only once or whether it can be used multiple times. – default true
  • expiration - The date and time at which the QR code expires and can no longer be used for iDEAL transactions. – defauts to +1 year
  • merchant_order_id - Your own order id.
  • size - In this field, the Merchant indicates the size of the QR code in pixels. The value must be between 100 and 2000 px. – default 200
  • return_url - URL to redirect the customer to after payment – optional

This information should be sent to the API’s /idealqr/ resource using an HTTP POST containing a JSON body. The API response will contain, in the qr_url field, the URL to the QR code.

Example order request:

    POST /v1/idealqr/ HTTP/1.1
    Authorization: Basic aHVudGVyMjo=
    Content-Type: application/json
    {
        "amount_changeable": false,
        "amount": 995,
        "currency": "EUR",
        "description": "Example order #1",
        "one_off": true,
        "merchant_order_id": "TEST001",
        "size": 200,
        "return_url": "http://www.example.com/",			
        "webhook_url": "http://www.example.com/"
    }

API reponse:

    HTTP/1.1 201 Created
    Content-Type: application/json
    {
        "amount": "9.95",
        "amount_changeable": false,
        "beneficiary": "Example Merchant",
        "description": "Example order #1",
        "expiration": "2020-09-23 11:28",
        "id": "1a4a46d1-e839-49e5-9f10-a3895a3d59e3",
        "merchant_id": "298939b0-cb8b-4e1d-b388-3efae9205fff",
        "merchant_order_id": "TEST001",
        "merchant_sub_id": 0,
        "one_off": true,
        "project_id": "9db1fc26-eab3-4b68-82e0-6c5dad856c89",
        "qr_url": "https://qr2.ideal.nl/ideal-qr/qr/get/1a4a56a1-e839-49e5-9f10-a3805a3d49e4",
        "return_url": "http://www.example.com/",
        "size": 200,
        "webhook_url": "http://www.example.com/"
    }

Handling the payment result

After a user scans the QR code; a regular iDEAL transaction will be created. After payment, the iDEAL service will redirect the customer to the URL supplied in the return_url, whether the payment was successful or not. The order and project details will be supplied in GET variables (order_id and project_id).

For example:

http://www.example.com/?order_id=4c6afd74-a840-4aab-b411-1e6e0636d341&project_id=b5f39273-44e7-4385-8e08-44612ef3e117

The merchant can either display a generic “thank you” page, or request the status of the order and use this information to perform a custom action.

To be able to recognize an iDEAL QR order we store the flag from-idealqr and we store the qr_id in the extra > idealqr_id field. Example of iDEAL order as the result of an iDEAL QR request:

{
    "amount": 995,
    "created": "2019-09-23T11:33:12.237535+00:00",
    "currency": "EUR",
    "description": "Example order #1",
    "extra": {
        "idealqr_id": "1a4a46d1-e839-49e5-9f10-a3895a3d59e3"
    },
    "flags": [
        "from-idealqr"
    ],
    "id": "b06ebdcb-972f-4e03-bdb4-8099bfb34861",
    "last_transaction_added": "2019-09-23T11:33:12.523240+00:00",
    "merchant_id": "298939b0-cb8b-4e1d-b388-3efae9205fff",
    "merchant_order_id": "TEST001",
    "modified": "2019-09-23T11:33:14.106042+00:00",
    "project_id": "9db1fc26-eab3-4b68-82e0-6c5dad856c89",
    "return_url": "http:\/\/www.example.com\/",
    "status": "processing",
    "transactions": [
        {
            "amount": 995,
            "balance": "internal",
            "created": "2019-09-23T11:33:12.523240+00:00",
            "credit_debit": "credit",
            "currency": "EUR",
            "description": "Example order #1",
            "events": [
                {
                    "event": "new",
                    "id": "38ff72e6-681d-4cf5-995c-8a443dfa1c64",
                    "noticed": "2019-09-23T11:33:12.682978+00:00",
                    "occurred": "2019-09-23T11:33:12.523240+00:00",
                    "source": "set_status"
                },
                {
                    "event": "processing",
                    "id": "5c0f10e8-0ef6-4f27-94db-f174b05a633e",
                    "noticed": "2019-09-23T11:33:12.785172+00:00",
                    "occurred": "2019-09-23T11:33:12.785172+00:00",
                    "source": "set_status"
                }
            ],
            "expiration_period": "PT30M",
            "id": "0aab2e41-98b3-4637-9c24-6d9f2bc81a72",
            "merchant_id": "298939b0-cb8b-4e1d-b388-3efae9205fff",
            "modified": "2019-09-23T11:33:14.133730+00:00",
            "order_id": "b06ebdcb-972f-4e03-bdb4-8099bfb34861",
            "payment_method": "ideal",
            "payment_method_brand": "ideal",
            "payment_method_details": {
                "consumer_bic": null,
                "consumer_city": null,
                "consumer_iban": null,
                "consumer_name": null,
                "issuer_authentication_url": "https:\/\/betalen.rabobank.nl\/ideal-betaling\/landingpage?random=e4179943e12b0ca52ed4035dd63180f39c9f393ed482bbcca13dd32ade970265&trxid=0030004422693169",
                "issuer_id": "RABONL2U",
                "status": "Open",
                "transaction_id": "0030004422693169"
            },
            "payment_url": "http:\/\/www.example.com\/",
            "project_id": "9db1fc26-eab3-4b68-82e0-6c5dad856c89",
            "status": "processing"
        }
    ],
    "webhook_url": "http:\/\/www.example.com\/"
}