Transaction Flow

In this chapter the transaction flows of two iDEAL payment types are described:

• Standard iDEAL payment
  • Without profile recognition
  • With profile recognition (based on debtor token)
• Fast Checkout iDEAL payment (based on browser cookie)

Additional requirements for the iDEAL payments are described in the chapter iDEAL requirements

Standard iDEAL Payment

An iDEAL transaction for a simple single payment is the basis of the iDEAL flow. The actual iDEAL transaction flow that the PSU follows, depends on where the iDEAL transaction is started at the Initiating Party (mobile app or browser, desktop browser) and where the payment authorization takes place at the ASPSP (mobile banking app, desktop browser, mobile browser). Next to this, it also depends on whether a PSU is already registered for iDEAL, and whether a registered PSU is recognized by the iDEAL Hub via a Debtor Token.

The full iDEAL transaction flow broadly follows the following steps:

1. Shopping Process: The PSU places an order at an Initiating Party and chooses iDEAL as payment method. If the Initiating Party makes use of Debtor Tokens, the Initiating Party shows the preferred ASPSP and IBAN of the recognized PSU alongside the iDEAL payment button.
2. Transaction Initiation: A transaction is created at the Open Banking Service using the Post /payments API, which responds with a redirect URL to the iDEAL payment page or the ASPSP directly.
3. Customer Recognition / ASPSP Selection: The PSU is redirected by the Initiating Party (or CPSP) to the iDEAL payment page, where he can choose an ASPSP or scan a QR code (depending on the web/app context). Alternatively, a recognized PSU (by means of browser cookie or debtor token) may be redirected directly to his preferred ASPSP or receive a push notification from his preferred ASPSP to authorize the iDEAL transaction (decoupled flow).
4. ASPSP Authorization: The PSU is presented with the transaction details at the ASPSP, where he authorizes the iDEAL transaction.
5. Transaction Confirmation & Return to Initiating Party: When the PSU authorizes the payment, a confirmation is sent by the ASPSP to the iDEAL Hub. If applicable, the PSU may be asked to register a profile with iDEAL. The iDEAL Hub informs the Open Banking Service of the payment status, who in turn informs the Initiating Party. In case the Initiating Party implemented the Post status API, they are informed of the payment status directly by the Open Banking Service. In case of a redirect flow, the PSU is ultimately redirected back to the Initiating Party.

Below are two example screen flows. The top one is using a mobile device throughout. The bottom one starts on a non-mobile device and switches to a mobile device for the ASPSP Authorization.

Figure 1 iDEAL transaction flow example on mobile

Figure 2 iDEAL transaction flow starts on non-mobile device (example)

For the initiation of an iDEAL payment two authentication flows are applicable; described in the table below.

Sequence diagrams

The sequence diagrams in this paragraph are examples of possible flows for standard iDEAL payments with and without profile recognition, they do not encompass all the possible flows.

In the diagrams below the sequence of requests is shown. The vertical green bars indicate which party is responsible for the session of the PSU. If a party has the session a screen can be displayed. Notice that in the iDEAL 2.0 flow the Initiating Party can receive a notification when the authorisation of the payment is finished on the ASPSP side. In order to receive this notification, the Initiating Party should implement the Post status API, so this can be called by the Open Banking Service. The initiating party also has the option to request the status by calling the Get /payments/status API of the Open Banking Service.

Redirect and no Debtor token

This is an example of an iDEAL payment where the PSU is not recognized by the iDEAL Hub. 

Redirect with newly generated Debtor token

The iDEAL payment product has the option to store information about the PSU, such as the favorite bank and the IBAN. In order to use this functionality, the Initiating Party should set the field 'UseDebtorToken = true' in a Post /payments request towards the Open Banking Service. If a new debtor token is generated by the iDEAL Hub the Open Banking Service will return, next to the Status of the payment in Post /status, a PsuID in Post /debtorToken. This PsuID can then be used in subsequent iDEAL payments request for the same PSU (again with 'UseDebtorToken' set to true). 

Redirect with existing Debtor token

The Open Banking Service also offers a separate API which can be used to retrieve the preferences of the PSU, the Get /preferences API.

In the sequence diagram below the Get /preferences api is the optional step in the beginning. This flow is using the Debtor Token to reduce the number of steps for the PSU to complete the payment (no ASPSP selection required in the iDEAL Hub).

Decoupled with existing Debtor token

This sequence diagram shows a possible decoupled flow, but is otherwise the same as the 'Redirect with existing debtor token' flow.

In a decoupled flow another device is used to authenticate and authorize the payment, this can be seen in the sequence diagram below by the fact that 2 sessions (green vertical bars) are active at the same time. The PSU doesn't leave the session with the Initiating Party, in the meantime a session is started on another device (for example a smartphone) which handles the interaction between the PSU and the ASPSP. The decoupled flow can potentially speed up the authentication process when bio-metrics are used in the ASPSP's app on the smartphone. 

If the following fields are provided in the Post /payments request a decoupled flow can be initiated by the ASPSP:

• HttpHeaderUserAgent
• PsuId
• UseDebtorToken = true

In case of a decoupled flow the Post /payments response will have 'UseWaitingScreen = true' field.

Fast Checkout iDEAL Payment

An iDEAL payment with iDEAL Checkout allows a PSU to centrally manage his shipping, invoice and contact details in its iDEAL profile and provide these to an Initiating Party as part of the iDEAL payment.

In an iDEAL payment with iDEAL Checkout, a PSU is redirected to the iDEAL Payment Page. If the PSU is recognized by a cookie and an iDEAL profile is detected, the shipping address preferences are shown to him on the iDEAL payment page. The PSU then confirms its preferred contact details and shipping address on the iDEAL payment page, after which he proceeds with the transaction through either a redirect to the ASPSP, a QR code scan, or a push notification to its mobile banking app. After the PSU has authorized the payment at the ASPSP, he is redirected back to the Initiating Party. Upon authorization, the Initiating Party receives confirmation of the payment (similar to a regular iDEAL transaction), which will additionally include the chosen contact details and shipping address of the PSU.

Currently only Dutch shipping addresses are allowed for PSUs

Below an example screen flow of a Fast Checkout iDEAL Payment.

Initiating an iDEAL Checkout transaction with the Open Banking v3 API

An iDEAL Checkout transaction can be initiated by indicating this in the FlowType field of the Post /payments. A breakdown of the transaction amount needs to be added to this call, which will be shown to the PSU during the iDEAL Checkout transaction flow alongside its shipping details.

Initiating an iDEAL Checkout transaction

• To mark a transaction as iDEAL Checkout, the field FlowType MUST be set to FastCheckout
• To initiate an iDEAL Checkout transaction, the AmountBreakdown group MUST be included in the POST /payments call.
  • This group MUST include both an OrderAmount and a ShippingCost. If no shipping costs apply, the field must be filled with 0.
• The sum of the OrderAmount and ShippingCost MUST be equal to the Amount field, which represents the total transaction amount to be payed by the PSU.
• To specify the desired iDEAL Checkout data to be received, the ExpectedCheckoutData group can be set. Only those data fields that are set to true will be included in the callback.

In a iDEAL Checkout transaction, the response of the Post /payments call will always include a URL to the payment page in the Links.RedirectUrl field.

Shipping amount and shipping/invoice address restrictions

• When initiating an iDEAL Checkout transaction, the Initiating Party MUST specify the desired iDEAL Checkout data to be received, which can be included in the payment initiation via the ExpectedCheckoutData group
  • The Initiating Party MUST comply with the General Data Protection Regulation (GDPR). The Initiating Party SHOULD only request the personal data which is needed to fullfill the agreement with the PSU;
• The Initiating Party MUST provide both an OrderAmount and ShippingCost.
• The PSU can only add Shipping and Invoice addresses in The Netherlands. Any other non-NL addresses are currently not allowed. Initiating Party's therefore can trust to receive only NL addresses.
• It is (currently) not possible to dynamically define or alter the shipping amount based on the PSU’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 PSU cannot or does not want to provide its iDEAL Checkout data, the transaction is canceled. This means that if an iDEAL Checkout transaction is initiated, a successful and payed transaction will always include the iDEAL Checkout data.

Selection/registration of iDEAL Checkout data by PSU

After initiating an iDEAL Checkout, the PSU is redirected to the iDEAL Payment Page. Here, the amount breakdown in order amount and shipping amount is shown, next to the regular payment details.

• If the PSU is recognized by a browser cookie, the known shipping address preferences from its iDEAL profile are shown, in addition to the regular profile preferences. Note that only the data fields indicated in ExpectedCheckoutData will be shown to the PSU (this applies to all iDEAL Checkout flows).
• Profile information presented will be partly masked and can only be fully shown if the PSU authenticates via its ASPSP.
• If a registered PSU does not have any shipping address registered with its profile yet, it will first be asked to provide an address before continuing with the iDEAL Checkout transaction.
• If the PSU is not recognized, it will first be asked whether the PSU has a registered iDEAL profile. In case of an existing profile, the PSU will be asked to select its ASPSP and is redirected to that ASPSP for authentication. After successful authentication, the PSU will return to the iDEAL payment page to view its (unmasked) profile and iDEAL Checkout data.
• At any time during the iDEAL Checkout flow, the PSU may choose to change its preferred address for the transaction or add a new address. This is done on the iDEAL payment page.
• If the PSU is not recognized and is a new PSU, the PSU is asked to register an iDEAL profile, including data for iDEAL Checkout.

Shipping data in transaction callback

After confirming the selected delivery details and preferred IBAN, the PSU is redirected to the ASPSP for authenticating and authorizing the payment. This is done at the ASPSP, similar to a regular transaction.

If the PSU was not registered with iDEAL yet, a registration flow was initiated at the iDEAL payment page.

After the PSU has confirmed the transaction payment at the ASPSP, the PSU’s iDEAL Checkout data (like shipping address) is added to the Post /status callback alongside the other payment details. The iDEAL Checkout data can be found in the DebtorInformation group. Note that only data fields that were indicated in the ExpectedCheckoutData will be included in the callback.

Sequence diagram

This iDEAL Fast Checkout flow is based on de the recognition of the PSU by the iDEAL 2.0 Hub based on a browser cookie. In the sequence diagram below the PSU is recognized. This flow will simplify the checkout screen of the Initiating Party; shipping, invoice and contact details are all handled by the iDEAL Hub. The shipping data is provided in the Post /status request or the Get /payments/status response after the payment was finalized at the ASPSP.