Standard iDEAL Payment (Direct Connection)

Owned by Currence
Last updated: Jun 10, 2024
8 min read

Transaction overview

An iDEAL transaction for a simple single payment is the basis of the iDEAL flow. 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

  3. Customer Recognition / Issuer Selection: The User is redirected by the Merchant (or CPSP) to the iDEAL payment page, where he can choose an Issuer, scan a QR code (depending on the web/app context) or receive a push notification from his preferred Issuer to authorize the iDEAL transaction.
    Note: if an IssuerID is provided in the transaction initiation, the User is redirected directly to the Issuer.

  4. Issuer Authorization: The User is presented the transaction details at the Issuer, where he 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. If applicable, the User may be asked to register a profile with iDEAL. The User is ultimately redirected back to the Merchant.

 

The actual standard iDEAL transaction flow that the User goes through, depends on

  • where the iDEAL transaction is started at the merchant (mobile app or browser, desktop browser)

  • where the payment authorization takes place at the Issuer (mobile banking app, desktop browser, mobile browser).

  • whether a User is already has an iDEAL profile, and whether a registered User is recognized by iDEAL (via a browser cookie).

  • whether an IssuerID is provided by the Acquirer in the transaction initiation (to be decommissioned)

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 initiation 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 initiation. 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.

Presentation of the iDEAL button for Standard iDEAL transactions

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.

  • As indicated, Issuer selection will in time move away from the Merchant environment to the iDEAL Payment Page for standard iDEAL transactions. If the Merchant still has the Issuer selection in place on its own environment, the following rules apply:

    • 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.

Transaction Initiation

To create a new iDEAL transaction, a request is made to the /transactions API. If a POST /transactions call is successfully processed by iDEAL, a transaction is created and iDEAL will return a response (201 Created) including the details of the created transaction and the data fields needed for continuation of the transaction.

Note that a valid JWT Access Token is required to be able to call the API, as well as a signing and mTLS client certificate. Please see Security for Direct Connection for more details.

For a full overview of further required and optional data fields in the POST /transactions API, see the API specifications: iDEAL - Merchant/CPSP API .

In case of a basic iDEAL payment transaction, the response to the /transactions API call includes a redirect link in the field links.redirecturl. The User must be redirected to this redirectURL where she can proceed with the payment.

The links.redirectURL will contain a link to the iDEAL payment page, unless an issuer.ID was provided in the transaction initiation. In that case, the links.redirecturl will contain an IssuerURL.

creditor.sub.name in case of a CPSPs

When no CPSP is involved in the transaction, all of the Merchant (i.e. creditor) details are provided upfront upon onboarding to the Acquirer and are inside the JWT Access Token (as in the example).

However, in case a CPSP is involved, the Merchant details must be provided per transaction by the CPSP in the body of the JSON message. The creditor.sub.name should be the name of the Merchant.

Note that

  • in case no CPSP is involved, the beneficiary name is presented to the payer (in payment screens and bank statement) as: “[merchant name]”.

  • in case a CPSP is involved, the the beneficiary name is presented to the payer as: “[merchant name] via [cpsp name]”

Transaction Description and reference

A description and reference must be provided to accompany the transaction. The description is communicated to the User during the iDEAL transaction and should indicate what the iDEAL transaction is for. The reference should contain an ID used by the Merchant to reference the transaction to its own order.

Both the description and reference show up as transaction details on the Users bank statement. Only the description is shown to the user during the iDEAL transaction

About the redirect to the links.redirecturl

The following should be known by the Merchant about redirecting to the links.redirecturl

  • If redirected from a browser, the redirect to the links.redirecturl MUST be performed from the browser window where the User selected iDEAL as payment method. The complete page of the Merchant must 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 links.redirecturl embedded within its own page, as this amongst others 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.

Example POST /transactions

curl -X 'POST' \ 'https://merchant-cpsp-mtls.idealapi.nl/v2/merchant-cpsp/transactions' \ -H 'accept: application/json' \ -H 'Request-ID: u06zf2cMq-w6ciUvZ8_MeVaQ4h' \ -H 'Authorization: Bearer {JWT access token}' \ -H 'Signature: {signature}' \ -H 'Content-Type: application/json' \ -d '{ "amount": { "amount": 1100, }, "description": "Cookie", "reference": "iDEALpurchase21", "creditor": { "countryCode": "NL" }, "transactionCallbackUrl": "https://checkout.company.com/transaction/webhook/91FA6EEC30844FAAB5", "returnUrl": "https://www.myshop.com/paymentHandling" }'

HTTP 201 Create - Transaction Creation Response Example

{ "transactionId": "8000000000000001", "createdDateTimestamp": "2022-06-01T07:47:34.898Z", "expiryDateTimestamp": "2022-06-01T07:47:34.898Z", "description": "Cookie", "reference": "iDEALpurchase21", "transactionType": "ONLINE", "transactionFlow": "STANDARD", "amount": { "amount": 1100, "type": "FIXED", "currency": "EUR" }, "creditor": { "id": "100000001", "name": "The Dutch CookieShop Company N.V.", "cpsp": false, "countryCode": "NL", "iban": "NL44RABO0123456789", "bic": "INGBNL2AXXX" }, "transactionCallbackUrl": "https://checkout.company.com/transaction/webhook/91FA6EEC30844FAAB5", "mcc": "5812", "links": { "redirectUrl": { "href": "string" }, "returnUrl": { "href": "https://www.myshop.com/paymentHandling" } }, }

For a full overview of further required and optional data fields in the POST /transactions API, see the API specifications.

Transaction Status retrieval and return to Merchant

After the User confirms an iDEAL transaction at her Issuing bank, she is returned to the Merchant via a browser redirect to the returnUrl that was provided in the transaction Initiation.

This redirect is usually the main trigger for the Merchant to present the final status to the User. If this status is not known to the Merchant yet, it should be able to retrieve this status from iDEAL.

There are two ways in which the status of the iDEAL transaction can be retrieved

  1. Status push via transaction callback

  2. Status pull via a GET /transactions/{transactionId}

Transaction Callback

Upon receiving the payment confirmation from an Issuer, iDEAL will notify about the updated payment status by calling the /transaction-callback API. The endpoint used for the /transaction-callback API is the value for transactionCallbackURL that was provided in the POST /transactions call. In the body of the request iDEAL will provide the transactionID and the transaction information, including the status of the transaction.

Upon receiving a call on above mentioned endpoint the receiving party must:

  • Confirm that the callback request was received through an HTTP 204 No Content response

  • Notify the merchant of the updated transaction status and other necessary transaction details

 

POST /transaction-callback example

{ "transactionId": "0001000000000001", "amount": { "amount": 1100, "type": "FIXED", "currency": "EUR" }, "description": "Cookie", "reference": "iDEALpurchase21", "createdDateTimestamp": "2022-06-01T09:48:59.486Z", "expiryDateTimestamp": "2022-06-01T09:48:59.486Z", "finalStateDateTimestamp": "2022-06-01T09:48:59.486Z", "status": "SUCCESS", "guaranteedAmount": 1100, "debtor": { "iban": "NL44RABO0123456789", "bic": "ABNANL2AXXX", "name": "Edsger Wybe Dijkstra" }, "issuerID": "RABONL2UXXX"" }

Transaction status request

Although the main means of being notified about the final state of a transaction is via the /transaction-callback, Merchants can also try to retrieve the last iDEAL transaction status via a status pull. If the status of a transaction is requested and the Merchant does not have the final status yet, the Merchant should retrieve the latest transaction status by making a GET request to the /transactions/{transactionId}.

The GET /transactions/{transactionId} must not be retried or polled in a way that unnecessarily strains the iDEAL Hub. In stead it may be tried once only in the following events:

  • The user ends up in the merchant environment and the final transaction state is not known (callback has not been received)

  • The transaction exceeds its expiryDateTimestamp and the final transaction state is not known

  • 24 hours after transaction creation when the final transaction state is not known

Example GET /transactions/{transactionId}

HTTP 200 - Transaction Creation Response Example

 

 

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