iDEAL for Payment Setup API

Last updated: April 30, 2026

To accept iDEAL payments, you must:

Create a payment setup.
Confirm the payment.
Redirect the customer to iDEAL.

Call the Create a payment setup endpoint.

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.api.checkout.com/payments/setups


1{
2  "amount": 2000,
3  "currency": "EUR",
4  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
5  "reference": "ORD-5023-4E89",
6  "billing": {
7    "address": {
8      "address_line1": "Keizersgracht 451",
9      "city": "Amsterdam",
10      "country": "NL"
11    }
12  },
13  "settings": {
14    "success_url": "https://example.com/payments/success",
15    "failure_url": "https://example.com/payments/failure"
16  }
17}

In the request body, provide the following:

Field	Description
`amount` number	The payment amount, in the minor currency unit. Minimum: 1 Required
`currency` string	Three-letter ISO 4217 currency code. Must be `EUR`. Required
`processing_channel_id` string	The processing channel's unique identifier. Required
`settings` object	Settings for the payment setup. Required
`settings.failure_url` string	The URL to redirect the customer to if the payment fails. Max length: 1024 Format: URI Required
`settings.success_url` string	The URL to redirect the customer to after a successful payment. Max length: 1024 Format: URI Required
`billing` object	The customer's billing details.
`billing.address` object	The customer's billing address. Required if `billing` is provided.
`billing.address.address_line1` string	The first line of the billing address. Required if `billing` is provided.
`billing.address.city` string	The city of the billing address. Required if `billing` is provided.
`billing.address.country` string	The two-letter ISO 3166 country code of the billing address. Must be `NL`. Required if `billing` is provided.
`billing.address.zip` string	The zip or postal code of the billing address.
`description` string	A description of the payment. Max length: 100
`payment_methods.ideal.description` string	Max length: 35
`reference` string	A reference you can use to identify the payment. For example, an order number. Max length: 80


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 2000,
5  "currency": "EUR",
6  "payment_type": "Regular",
7  "reference": "ORD-5023-4E89",
8  "description": "iDEAL payment",
9  "payment_methods": {
10    "ideal": {
11      "status": "ready",
12      "flags": []
13    }
14  },
15  "available_payment_methods": [
16    "ideal"
17  ],
18  "settings": {
19    "success_url": "https://example.com/payments/success",
20    "failure_url": "https://example.com/payments/failure"
21  }
22}

The response returns a payment_methods object, which contains the payment methods enabled on your account.

Providing all required fields sets the payment_methods.ideal object to a ready status.

Confirm the payment by calling the Confirm a payment setup endpoint and provide:

The payment setup id as the {id} path parameter.
ideal as the {payment_method_name} path parameter.

post

https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/ideal

If you receive a 202 Success response with a payment id and a status field set to Pending, your request was successful.


1{
2  "id": "pay_yndlioum4gau3oizxihvzdgp4i",
3  "status": "Pending",
4  "customer": {
5    "id": "cus_xalxia5mzjau3fv5gkuylu3xla",
6    "email": "hannah.bret@example.com"
7  },
8  "_links": {
9    "self": {
10      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_yndlioum4gau3oizxihvzdgp4i"
11    },
12    "redirect": {
13      "href": "https://sandbox.ideal-acquiring.ing.nl/ideal/iDEALv3/issuer/simulation?transactionId=0051100036109376&random=1d2e57594bf6c948c84014856f869349ba131ba25cefe5cd57c99dd396f7a40c"
14    }
15  }
16}

Redirect the customer to the redirect link's href from the response. The customer completes the payment on the iDEAL page and is then redirected back to your settings.success_url or settings.failure_url.

Note

For security reasons, iDEAL forbids using custom-made in-app browsers for redirection. Checkout.com recommends that you open the device's default browser to display the redirect. If you do want to use an in-app web view, you must use SFSafariViewController for iOS or Chrome Custom Tabs for Android.

Confirmation of an iDEAL payment is communicated only through webhooks. When you receive a payment_captured webhook, the transaction has been completed successfully. Until the payment_captured webhook is received (response code 10000), all payments are labeled as Pending.

iDEAL for Payment Setup API

Create a payment setup

Information

Request example

Response example

Confirm the payment

Request example

Response example

Redirect the customer

Note