iDEAL
Last updated: November 6, 2024
Information
iDEAL is also available through Flow. Flow enables you to accept payments on your website using Checkout.com's global network of payment methods with a single integration.
Note
iDEAL have updated their central technical infrastructure. To maintain your existing integration, you must update your integration with iDEAL Hub by December 31, 2024.
iDEAL enables customers to perform purchases with a direct online transfer from their bank account to your merchant bank account, using their mobile banking app or online banking environment.
When a payment is completed, iDEAL sends you an online payment guarantee so you can deliver goods and services right away.
Information
To enable iDEAL payments on your account, contact your Account Manager or [email protected].
Model | Collecting |
|---|---|
Payment flow | Redirect |
Payment method type | Online banking |
One-step payment | |
Authorization | |
Capture | |
Refund | |
Partial refund | |
Chargeback | |
Recurring payment |
iDEAL payments follow this process:
- Request a payment
- Redirect the customer
- Consume webhook notification with the result of the payment
- Refund a payment
Use the details below to set up your request. To get a detailed view of all required and optional fields, see our API reference.
post
https://api.checkout.com/payments
Information
If a customer ID or email is not provided in the request, then we automatically create a customer profile and return the customer id in the response.
If you receive a 202 Success response with a payment id and a status field set to Pending, your request was successful.
Redirect your customer to the redirect link’s href in the above response. The redirect transfers the customer to their bank's website where they are required to enter their authorization details; if successful, the payment can be approved.
Ensure that you open the redirect URL in the same window where your customer selected iDEAL as the payment method.
Note
For security reasons, iDEAL forbids using custom-made in-app browsers for redirection. We recommend 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.
Once completed, the customer is transferred to your predefined success or failure URL. Confirmation of an iDEAL payment is communicated only through webhooks. When you receive a payment_captured webhook notification, the transaction has been completed successfully. Until the payment_captured webhook is received (response code 10000), all payments are labeled as Pending.
To retrieve details about the payment, you can use either the id found in the payment response or the cko-session-id from the success/failure URL. For example, https://www.checkout.com/order/succeeded?cko-session-id=. For details about all required and optional fields, see our API reference.
Note
The cko-session-id expires 15 minutes after being created.
get
https://api.checkout.com/payments/{id}
If the customer fails to complete their payment, we will automatically void the payment in 10 minutes and send a payment_expired webhook.
If the customer cancels their payment, we will send a payment_canceled webhook.
When using iDEAL, you may receive the following webhooks.
| Webhook | Description |
|---|---|
| Occurs when a payment request has successfully initiated. |
| Occurs when the customer has approved the payment on the banking page. |
| Occurs when a capture is successful. |
| Occurs when a capture is declined. |
| Occurs when the customer has canceled the payment or the payment has failed. |
| Occurs when the payment has expired. |
| Occurs when a refund request has successfully initiated. |
| Occurs when a refund is successful. |
| Occurs when a refund is declined. |
iDEAL supports both partial and full refunds. You can refund a payment through the Dashboard or using the refund endpoint of the Unified Payments API.
Note
To start testing, you'll need to:
- create a test account, and
- contact your Account Manager or Integrations Engineer to activate iDEAL payments in the sandbox environment.
- Create an iDEAL transaction.
- Browse to the redirect link in the transaction response.
- In your browser, select the TESTNL2A bank.
- Select Success when asked which test simulation you want to run.
You should now be redirected to your predefined success URL.
After selecting the TESTNL2A bank, you can select any payment state you want to test from the bank's UI.
Note
When you test a payment refund, the transaction is likely to remain in a deferred refund state. Contact us at [email protected] to request triggering a simulation batch job that ensures the completion of the refund.