A Developer’s Guide to the new iDEAL

New infrastructure

The new infrastructure introduces the iDEAL Hub and a centralized payment page where the users can select their bank. The goal is to facilitate adoption and streamline the onboarding process for banks, issuers, and payment providers. Shoppers will benefit from experiencing a consistent bank selection flow across different web shops, making the process familiar and trusted.

iDEAL profiles

Consumers will be able to save their delivery details and preferred accounts, creating an iDEAL profile via their issuer bank. They can share this information with a webshop, completing the order and payment in one step. 

Payment flows

Profiles will help recognize returning users and make the payment faster by offering different options, such as a QR code, the iDEAL payment page, or a one-click payment checkout.

The significant change in the iDEAL payment flow is the bank selection process. The list of available banks will no longer be part of the checkout form but will instead be available on the new iDEAL payment page. The checkout page must redirect shoppers to the iDEAL payment page, where iDEAL will handle both bank selection and payment execution.

This is a necessary compliance change that requires all merchants to update the existing integrations.

When adding iDEAL as a new payment method, for example when developing a new payment integration or if you configure a new merchant account, iDEAL 2.0 is enabled by default.

For existing integrations on TEST we have configured the new iDEAL 2.0 payment method next to the existing one: update your payment integration and, when you are ready to test, activate iDEAL 2.0 in your Customer Area.

Update your payment integration

The changes required depend on the type of integration.

API-only

API-only integration is a method of integrating Adyen APIs where developers prefer to handle their checkout forms and user interfaces. This type of integration only requires one change: removing the list of banks from the Checkout page.

Your payment integration must initiate an iDEAL payment using the Adyen Checkout "/payments" API endpoint. Developers will no longer have to pass the issuer chosen by the shopper:

Plugins

When using one our plugins to connect to an existing ecommerce, you only need to upgrade the relevant plugin:

• Adyen Magento v9.6.0+

• Salesforce Commerce Cloud v24.3.0+

Web Drop-in and Components

Payment integrations that embed the Web Drop-in or Components should upgrade the version of Adyen Web library to v5.65.0 or higher. 

The latest Adyen Web versions will no longer display the list of banks to the shopper, but only the redirect button to perform the payment on the iDEAL page.

Good to know

Because the bank selection picklist is no longer provided, you can safely  remove any custom validation designed for the previous version of Adyen Components. This is especially important if you have hidden the default Component button and implemented a custom one.

Additionally, note that iDEAL optional configurations from previous versions are no longer available and should be removed.

Check out our sample applications on GitHub to see how to use the Web Drop-in and Components and make a payment with iDEAL. 

iOS and Android SDKs

We have updated our iOS and Android mobile SDKs: make sure to use a version released after July 2024.

For iOS, the additional configuration for iDEAL is no longer available and can be removed.

Hosted Checkout

No changes are required.

Activate iDEAL 2.0 in your Customer Area (existing integrations)

Log into the Customer Area, go to the "Payment methods" screen and select iDEAL with “iDealSim” acquirer. The next step is to click on “More actions” and choose the option ”Deactivate”. Then select the other iDEAL payment method and activate it to route the iDEAL payments to the new infrastructure.

From then on, all iDEAL payments will be performed using the new protocol.

The updated iDEAL allows storing the shopper's preferred bank, enabling direct redirection to the bank without requiring the selection on the iDEAL page.

Note that this feature is available only with the Advanced Flow integration. 

Save the shopper’s Bank Identification Code (BIC)

Adyen can send the bank information used by the shopper for the iDEAL payment through the payment Authorization Webhook. To enable this, navigate to the Customer Area and configure the Webhook by enabling the "Include Bank Account Details" option under "Additional Settings." 

After the iDEAL payment is completed, you will receive the Authorization Webhook. Extract the BIC number from the payload and store it for future use. You can then include it in the next iDEAL payments, indicating the BIC of the shopper's preferred bank.

Initiate the payment

To initiate an iDEAL payment using the shopper’s preferred bank, invoke the Checkout "/payments" endpoint from your server-side application, as explained in the Advanced Flow integration. Ensure you set the `issuer` field with the previously stored BIC.

If the shopper decides to use a different bank, make a new iDEAL payment without the "issuer" attribute and let the iDEAL page manage the bank selection.

The new iDEAL infrastructure provides an updated sandbox for testing. It's extremely important to validate your Adyen integration on our TEST environment to simulate the shopper's flow and test possible payment outcomes. 

When landing on the Bank Selection page, choose the "TESTNL2A" issuer to access the test page. 

Each scenario will trigger a different response that simulates the intended payment flow. Refer to the Adyen Docs "Test and Go Live" page to find out what response to expect.

The new iDEAL 2.0 significantly enhances the shopper payment experience. It also streamlines the integration process for developers who want to offer iDEAL, thanks to introducing a centralized iDEAL page, a simplified bank selection process, and iDEAL shopper profiles. To align with these changes, developers are required to update their existing integrations by April 1st, 2025. 

In the Adyen TEST environment, we’ve made the migration to iDEAL 2.0 straightforward: simply update your existing integrations and test the new iDEAL flows.

On the LIVE platform, the configuration already supports iDEAL 2.0. Once testing is complete, merchants can seamlessly transition to the new iDEAL without additional changes.

Check out the iDEAL page and adopt the new iDEAL to offer shoppers the best experience with the most trusted payment method in the Netherlands.