iDEAL QR

Only the Rabobank, Knab, ING and ABN AMRO banking apps can scan the QR code directly. When having another bank the customer should use their camera with built in QR scanner or a dedicated QR scanner. The customer will then be send to a payment page where they’ll be able to select their bank and complete the transaction as normal.

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. – defaults 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

The following is an example of an iDEAL QR request:

POST /v1/idealqr/ HTTP/1.1
Authorization: Basic aHVudGVyMjo=
Content-Type: application/json

{
    "amount_changeable": false,
    "amount": 995,
    "currency": "EUR",
    "description": "Example iDEAL QR order",
    "one_off": true,
    "merchant_order_id": "TEST001",
    "size": 200,
    "return_url": "https://www.example.com/",            
    "webhook_url": "https://www.example.com/"
}

The API response will contain, in the qr_url field, the URL to the QR code:

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": "https://www.example.com/",
    "size": 200,
    "webhook_url": "https://www.example.com/"
}

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. The following is an example of an iDEAL QR request order status:

{
    "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\/"
}