Generic Merchant info and requirements on the New iDEAL

Owned by Currence
Last updated: Apr 10, 2024
11 min read

Purpose of this document

The goal of this document is to provide an overview of general information and requirements for Merchants (and some cases CPSPs) that complement the technical connection specifications from other documents. Regardless of connection type, this general information applies to all Merchants and CPSPs that offer iDEAL as a payment means.

Connection Types

As a Merchant or CPSP, there are roughly two alternatives to connect to iDEAL.

  1. Connecting to an iDEAL Acquirer or CPSP.

  2. Connecting directly to the iDEAL Hub (for more details see Implementation Guide for iDEAL Merchant/CPSP Direct Connection )

Please contact your Acquirer/(C)PSP to see which connection alternatives it allows and on the specifics of these alternatives.

iDEAL Product Features

Currently, in the New iDEAL, iDEAL offers roughly 3 different product features, that require different implementation.

  1. Standard iDEAL transaction - iDEAL Pay Fast (with cookie)

  2. Transaction with User token - iDEAL Pay Fast (with token)

  3. Transaction with Checkout - iDEAL Snel Bestellen (iDEAL Checkout)

These will be explained in further detail in the below sections.

1. Standard iDEAL transaction - iDEAL Pay Fast (with cookie):

General

A standard iDEAL transaction for a simple single payment is the basis of the iDEAL flow. The actual iDEAL transaction flow that the User follows, depends on where the iDEAL transaction is started at the merchant (mobile app or browser, desktop browser) and where the payment authorization takes place at the Issuer (mobile banking app, desktop browser, mobile browser). Next to this, it also depends on whether a User is already registered for iDEAL, and whether a registered User is recognized by the iDEAL Hub (via a browser cookie).

The full iDEAL transaction flow broadly follows the following steps:

  1. Shopping Process: The User places an order at a Merchant and chooses iDEAL as payment method.

  2. Transaction Initiation: A transaction is created at the iDEAL Hub, which responds with a redirect URL to the iDEAL payment page or the Issuer.

  3. Customer Recognition / Issuer Selection: The User is redirected by the Merchant (or CPSP) to the iDEAL payment page, where she can choose an Issuer or scan a QR code (depending on the web/app context) and/or proceed with her pre-filled preferred bank/IBAN. Alternatively, a User may receive a push notification from her preferred Issuer to authorize the iDEAL transaction.

  4. Issuer Authorization: The User is presented the transaction details at the Issuer, where she authorizes the iDEAL transaction.

  5. Transaction Confirmation & Return to Merchant: When the User authorizes the payment, a confirmation is sent by the Issuer to the iDEAL Hub. The iDEAL Hub informs the Acquirer, CPSP or Merchant of the payment status on the transaction callback URL. Lastly, the User is ultimately redirected back to the Merchant.

image-20240306-135544.png
Transaction flow started on mobile device (example)
image-20240306-152523.png
Transaction flow started on non-mobile device (example)

For interactive UX flows see: iDEAL Pay Fast (cookie)

2. Transaction with User token - iDEAL Pay Fast (with token)

General

For an enhanced User flow for returning Users, the Merchant may want to make use of iDEAL User Tokens. The iDEAL User Tokens allow the Merchant to present the User’s preferred IBAN within its Merchant Domain, and shorten the payment journey and in some cases prevent a redirect all together.

If a Merchant wishes to make use of iDEAL User Tokens for its Users, the following applies:

  • The User MUST hold an account with the merchant;

  • To retrieve the preferred bank and (masked) IBAN of the User, the Merchant MUST provide an iDEAL User Token received in a previous transaction. This User token uniquely identifies the User at the Merchant;

  • The Merchant MUST be able to recognize the User on a return visit;

  • The Merchant MUST only use iDEAL User Tokens that were received in the last transaction for that User

Please note that an iDEAL User Token can only be linked to one iDEAL profile, and therefore only one User Token can be registered per Merchant account per User.

Presentation at Merchant in case a transaction with iDEAL User Tokens is used

  • Upon receipt of the preferred Issuer and (masked) IBAN of the User, the Merchant MUST display these together with the iDEAL payment button;

  • As an alternative, the Merchant MUST provide the User the option to select a different bank (a “Change” option)

  • In case the User indicates she wants to use anther IBAN/Issuer to pay for the iDEAL transaction (triggers the “Change” option), a normal transaction initiation without a User token provided should be initiated. This way, a link to the payment page is returned to which the User can be redirected. Here the User can select another Issuer.

A transaction initiation with User Token should not be initiated in this case, because then a push notification is attempted to her preferred IBAN, which could confuse the User (as she indicated she wanted to choose another IBAN/Issuer).

As a response to an iDEAL transaction initation with User token, the Merchant will receive both a redirectURL AND an indication on how the Merchant should continue the transaction:

  • REDIRECT: The Merchant should redirect the User to the redirecturl provided. For this redirect, all the same specifications apply as a transaction initiated without the iDEAL User Token.

  • PUSH_SENT_SHOW_WAITING_SCREEN: The Merchant MUST show a ‘Waiting for confirmation’ page. See below for presentation requirements

'Waiting for Confirmation' presentation

The 'Waiting for confirmation' page has the following presentation requirements:

  • There is a <Back> option, which leads the User back to the previous page of the Merchant;

    • Upon triggering this <Back> option, the merchant MUST check the status and if needed make a call to retrieve the status of iDEAL payment;

      • When there is no final status available, the merchant MUST inform the User that the payment is not finalised;

      • When there is a final status is available, the Merchant MUST inform the User about that status (payment successful, payment failed, etc.) and follow up with the applicable action;

  • There is a <Didn’t receive notification> button, which leads the User to the iDEAL Payment Page redirectURL to finalise the payment;

  • A message is displayed which informs the User about the action that is required, for example: ‘Tap the notification on your phone to pay with the following bank’;

    • The Issuer name and logo is displayed;

This page can be in the look and feel of the Merchant.

 

 

For interactive UX flows see iDEAL Pay Fast (token)

3. Transaction with Checkout - iDEAL Snel Bestellen (iDEAL Checkout)

General

Merchants may want to make use of the iDEAL Snel Bestellen. this feature allows the user to pay with iDEAL and simultaneously provide its saved shipping address to the Merchant in one go, without having to create a Merchant account or going through a guest checkout at the Merchant first.

  • When initiating an iDEAL Snel Bestellen transaction, the Merchant MUST specify the desired iDEAL Snel Bestellen data to be received, which can be included in the transaction initiation

    • The Merchant MUST comply with the General Data Protection Regulation (GDPR). The Merchant SHOULD only request the personal data which is needed to fulfill the agreement with the User;

  • The Merchant MUST provide both an order amount and shipping costs separately, as they will be displayed separately on the iDEAL Checkout payment page.

  • The User can only add Shipping and Invoice addresses in The Netherlands. Any other non-NL addresses are currently not allowed. Merchants therefore can trust to receive only NL addresses.

  • It is (currently) not possible to dynamically define or alter the shipping amount based on the User’s chosen shipping address. The shipping amount can only be provided one time in the transaction initiation. The shipping amount can also be 0.

  • In case the User cannot or does not want to provide its iDEAL Snel Bestellen shipping details, the transaction is canceled. This means that if an iDEAL Snel Bestellen transaction is initiated, a successful and paid transaction will always include the iDEAL Snel Bestellen shipping details.

Presentation on Merchant environment in case iDEAL Snel Bestellen is used

  • To indicate to Users that iDEAL Snel Bestellen is offered the Merchant MUST adhere to the iDEAL Snel bestellen button: brand guidelines

  • Before the User selects iDEAL Snel Bestellen, the applicable shipping costs MUST be communicated to the User, to prevent that the User is confronted with a higher amount in the iDEAL screens than expected;

  • The Merchant MUST confirm the datafields, received from Currence, to the User, preferably on the order confirmation screen.

 

For interactive UX flows, see iDEAL Snel Bestellen (Checkout)

General info and requirements on iDEAL payments

The below sections include general information and requirements on iDEAL.

Issuer Selection moves to the iDEAL Hub

Issuer Selection and IssuerID

In the new iDEAL, the selection of the Issuer is to move from the Merchant or CPSP environment to the central iDEAL environment. This also means that it will not be possible to provide an IssuerID anymore with an initation of an iDEAL transaction. To facilitate a smooth migration, for a prolonged period of time it will still be possible to let the user select the Issuer at the Merchant or CPSP and to provide an IssuerID in the transaction initation. This only holds for basic iDEAL transactions (so not for e.g. Fast Checkout transactions or transactions with an iDEAL User Token).

Note that in case an IssuerID is provided in the transaction initiation, the response will always include an IssuerURL and the user will always be redirected directly to the Issuer.

Therefore the following applies:

  • The Merchant MUST NOT provide an Issuer list to the User together with his iDEAL payment button. Issuer selection will be done on the iDEAL Payment Page.

    • Only for a limited period of time, Merchants that have not fully implemented the new iDEAL MAY still provide an Issuer list to the User. If the Merchant still chooses to show the Issuer list, the Merchant MUST provide the chosen Issuer as part of the iDEAL transaction request.

    • An exception to this rule involves transactions that follow from iDEAL QR. For these iDEAL transactions, still an IssuerID is needed to successfully complete the iDEAL payment.

Redirecting of Users

As a response to an iDEAL transaction initiation, the Merchant will receive a redirectURL, which is either an IssuerURL (directing the user directly to the Issuer domain) or a Payment Page URL (directing the user to the iDEAL Payment Page).

  • If redirected from a browser, the redirect to the IssuerURL or iDEAL Payment page MUST be performed from the browser window where the User selected iDEAL as payment method. The complete page of the Merchant shall be replaced by the complete iDEAL Payment page.

    • Merchants MUST NOT open the redirect to the iDEAL Payment page or IssuerURL in a new browser window.

    • Merchants MUST NOT present the iDEAL Payment page or IssuerURL embedded within its own page, as this disallows recognition of a cookie.

  • If redirected from a Merchant app, the redirect MUST take place outside the app in the default browser of the user.

Merchants MUST NOT redirect users in a custom made in-app webview browser. Doing so will disallow for users to be redirected to their mobile banking apps and will seriously breach privacy regulations.

Exceptions to the above are the use of  SafariViewController for Apple iOS and Chrome Custom Tabs for Android. However be aware that these may not correspond to the user’s default browsers, so that user recognition based on cookie might not work.

  • During the migration period to the updated iDEAL specifications, the Merchant is still allowed to share a preferred Issuer (for example when the Merchant also stores this preference). This feature will be discontinued after the migration period ends.

Retrieving the Status of the transaction

  • If the Merchant has not yet received a confirmation of the payment status when the User opens the returnURL, the Merchant MUST retrieve the transaction status by calling the status API of the Acquirer.

  • The Merchant MUST inform the User of a success status of the transaction, so that the User is certain that the payment status was correctly received by the Merchant.

  • The Merchant MUST NOT poll the status and MUST adhere to the retry scheme

Presentation of iDEAL on Merchant environment

There are some rules regarding the presentation of iDEAL on the Merchant's environment. The main purpose of these is to create a uniform user experience for Consumers whenever and wherever they pay with iDEAL.

  • The iDEAL payment option must be presented in the list of payment options in such a way that it receives at least the same amount of attention as other payment options.

  • The rules on presentation the iDEAL Payment button and the iDEAL logo can be found here: iDEAL logo usage guidelines .

    • In cases where the iDEAL logo cannot be displayed at the required size on a mobile device the mandatory free space of 15px around the logo may be reduced to accommodate the requirements of the mobile device.

  • After selection by the Consumer of the Issuing bank, the Consumer should be immediately redirected to the Issuer redirectURL.

  • All Issuers must be shown in a list (e.g. dropdown list or list of radio buttons) in alphabetic order

  • The list should be accompanied by the instruction phrase "Kies uw bank" (UK: "Choose your bank"). In case of an HTML <SELECT>, the first element in the list states this instruction phrase and is selected by default (to prevent accidental Issuer selection).

  • It is not allowed to exclude or grey out any active Issuers from the Issuer list. In case of communication a new Issuer, the Issuer list must be updated within one month (preferably earlier).

  • The Merchant may preselect an Issuer, but only to allow for an improved user experience (e.g. if the Consumer has previously initiated an iDEAL payment with a specific Issuer).

  • The Consumer must however always be offered the possibility to alter the preselected Issuer.

Other generic information on iDEAL

Expiration period

Note that Merchants may define the expiration period of a transaction if the Acquirer/PSP connection type allows you to do so. This expiration period defines the time the User has to complete the iDEAL transaction at its Issuer. For time-critical payments (e.g. ticketing) it may be useful to set the expiration period lower than the default, which is 20 minutes.

Merchant name on Bank Statement

Depending on whether a Merchant has a contract with a CPSP or with an Acquirer, the actual Merchant name stated on the users banking statement differs. When implemented correctly, in case of a contract with CPSP, the merchant name will show as [MerchantName] via [CPSPname]. In case of a direct contract with an Acquirer, it will state only [MerchantName].

Use of Payment links

Merchants may send their users iDEAL payment links via email, WhatsApp, text message or any other channel. This way they can e.g. offer their customers the option to pay later for electronic invoices or a (monthly) subscription fee.

There are specific requirements Merchants must adhere to when offering iDEAL payment links. These can be found on the iDEAL website .

Copyright © Currence iDEAL B.V. All rights reserved.