iDEAL Merchant Integration Guide (EN) (to be deprecated)

iDEAL Merchant Integration Guide (EN) (to be deprecated)

 

Version: 3.6
Oct 9, 2020

  • Push the icon with drie dots to the upper right

  • Choose "Export to PDF"

  • Wait until the PDF Export is done

  • Push Download to download the PDF

EN/NL

Terms and conditions

Terms and conditions for provision of the iDEAL Merchant Integration Guide:

  1. Scheme Owner Currence iDEAL B.V. provides the iDEAL Merchant Integration Guide to Acquiring banks which distribute it to (potential) Merchants and Payment Service Providers to enable them to form a good idea of what the implementation of the iDEAL product would involve and assess how any future use of iDEAL could affect their business operations.

  2. Currence iDEAL B.V. reserves the right to deny access to the iDEAL Merchant Integration Guide to (potential) Merchants and Payment Service Providers on reasonable grounds, in consultation with the Acquiring bank with which the Merchant/PSP has a contract.

  3. The iDEAL Merchant Integration Guide is explicitly and exclusively provided for the purpose mentioned above, and no other use is permitted. No rights can be derived from the information provided in this document or the accompanying notes. Currence iDEAL B.V. is in no way liable for the consequences of later changes to the iDEAL Standards or the iDEAL Merchant Integration Guide. If banks or other interested parties take decisions and/or make investments on the basis of the information that they obtain via the iDEAL Merchant Integration Guide, Currence iDEAL B.V. accepts no liability for this whatsoever.

  4. The iDEAL Merchant Integration Guide is based on the information in the iDEAL Standards documents. In the event of any discrepancy between the iDEAL Merchant Integration Guide and the iDEAL Standards documents, the text in the iDEAL Standards documents shall prevail.

For any questions concerning this document or requests for further information, please contact your iDEAL acquiring bank or Collecting Payment Service Provider


Contents


1. Introduction 

1.1 Target audience

iDEAL Merchants are organisations (Merchants) that want to receive iDEAL payments and have signed an iDEAL contract with a bank. This document is intended for iDEAL Merchants that want to connect to the iDEAL platform of the Acquiring bank they have chosen, and provides a description of all messages that are exchanged between the Merchant and the bank. The messages that are exchanged between the Issuer and the Merchant bank (Acquirer) are not of importance to the Merchant, and therefore will not be discussed in this document. This document is not bank specific, which means that only generic iDEAL specifications are mentioned in this guide. Please contact your Acquiring bank for any information or support on a bank specific connection or implementation.

1.2 Document structure

Chapter 2 provides an overview of all parties involved in iDEAL, and the various messages that are exchanged within the scope of an iDEAL transaction. The overall structure of the exchanged messages is outlined in the third chapter. Chapter 4 describes the Directory protocol, which provides the list of Issuing banks within iDEAL. The Payment protocol is described in chapter 5. The Query protocol, concerning actual status of an iDEAL transaction, is explained in chapter 6. The handling of errors and exceptions is discussed in chapter 7. Chapter 8 describes the security of iDEAL messages. Chapter 9 contains information about the iDEAL presentation (brand and logo). Chapter 10 describes some best practices and common implementation pitfalls.

1.3 Definitions of internet and online banking

In this document there are many references to the 'internet banking' or 'online banking' services of a Consumer bank. For Consumer banks that implement iDEAL Mobile, this should always be read as 'internet banking and/or mobile banking'. For every instance where internet or online related terminology is used, please interpret this as including the mobile channel. Where mobile use of iDEAL leads to specific additional requirements for iDEAL, this is indicated separately in the text.

1.4 Revisions

Version

Description

Release date

Version

Description

Release date

0.8

First English version for review by Currence

25-06-2009

2.2.1

Final version reviewed by Currence

30-06-2009

2.2.2

Added extra requirement for Query protocol collection duty

10-09-2009

2.2.3

Added passage greying out in Issuer list
Added passage increasing chance of success web shops
Added passage payment flow
Adjustment passage redirect to Issuer
Added passage Consumer error messages
Added passage entrance codes
Added Merchant-Acquirer XSD scheme

19-05-2010

3.3.0

Final version for approval by CAB

09-01-2012

3.3.1

New version based on iDEAL 3.3.1 Standard

27-03-2012

3.3.1 corrected

Corrections applied to OpenSSL example syntax

22-10-2012

3.3.1 correction November

Minor corrections on use of Byte Order Mark

08-11-2012

3.3.1 correction November II

Minor correction on use of empty fields

20-11-2012

3.3.1 corrections July

  • Clarification on XMLdsig and RmtInfo

  • TransactionCreateDateTimestamp,

  • Removed temporary field length conditions

  • Clarified supported character set

  • Clarification on use of canonicalization method

  • Correction in the openssl command for creating a certificate

  • Removed information on the Nederlandse credit transfer

  • Added information on platform versions supporting RSA with SHA-256 digital signatures

03-07-2013

3.3.1 corrections January 2014

  • Supplementary information on handling of errors during execution of payment protocol and status protocol

01-02-2014

3.3.1 corrections February 2014

  • Mobile addendum and quick guide have been integrated for additional information about Mobile Implementations.

17-03-2014

3.3.1 corrections October 2014

  • Added rule regarding the redirect to the Issuer in prargraph 5.5.

08-10-2014

3.3.1addition February 2015

  • Changes made to links to new iDEAL.nl website

  • Explanation to AP2910 error code

  • Explanation to use Merchant Signing certificates

15-02-2015

3.5

  • General presentation improvements

  • Added 3-minutes trigger for query protocol

  • Generalization of Issuer Selection List presentation requirements

  • Use of Universal Links and Android App links for Merchant Redirect iDEAL mobile

  • Support for at least TLS 1.1 is required

  • General clarification on common implementation errors

  • Consumer message inconsistency adjusted

  • Removed amount verification requirement in StatusResponse

Q3 2017

 


2. Overview 

2.1 What is iDEAL?

iDEAL was developed by the Dutch banking community in order to facilitate easier payment for online products and services. iDEAL enables direct and secure real-time online payments between bank accounts of Consumers and iDEAL Merchants.
The main characteristics of iDEAL are:

  • Real-time payment through accepted and trusted Internet banking that is already familiar to Consumers

  • Real-time payment authorisation for the Consumer and real-time confirmation to the Merchant by the Acquiring bank, followed by the irrevocable transfer of funds to the Merchant

  • Suitability for online delivery (e.g. downloads, mobile top-ups), offline delivery (e.g. goods) and time-critical payments (e.g. airline tickets)

  • Offers the flexibility to make payments for many different purposes (e.g. charitable donations, telephone/e-mail orders)

In practice, nearly every Consumer that uses Internet banking with one of the Issuing banks that support iDEAL can pay with the iDEAL payment method.

2.2 What is iDEAL Mobile?

iDEAL is an online payment method for the Dutch market. Although it was originally developed for use with internet banking services, it is now also possible for Issuers to create iDEAL implementations based on mobile banking services like mobile web sites or mobile apps. This is called iDEAL Mobile.
The main characteristics of iDEAL Mobile are:

  • There are no changes in the messages sent between Consumer bank and Merchant bank and no changes in messages sent between Merchant and bank;

  • Merchant and Consumer do not need to take extra steps for a mobile iDEAL transaction. The redirecting of the Consumer to the mobile banking channel is done automatically by the Consumer's bank; For banks that support iDEAL in their mobile banking app, the Consumer can choose whether to pay using the mobile web browser or the mobile banking app.

  • iDEAL Mobile is based on the same mechanisms to ensure trust, security and convenience as used in a desktop environment. In cases mobile technology does not support the same technical security measures as a desktop computer the bank will implement alternative measures to compensate.

Every Consumer that uses internet banking with one of the Issuing banks that supports iDEAL can pay with the iDEAL payment method on a mobile device (although it may be necessary for a Consumer to download and register a mobile application). Those Issuers that do not (yet) have an iDEAL Mobile implementation or that have an implementation that doesn't reach the majority of Consumers will still be able to process transactions through their regular (desktop focussed) iDEAL pages on a mobile device's browser.

2.3 Four party model

There are at least four parties involved in an iDEAL transaction. First there is the Consumer that buys a product or service online. The Consumer buys this from a Merchant that offers the iDEAL payment method; usually this is a web Merchant. The web Merchant is usually referred to as "Merchant" by the banks.The Consumer has a relation with his bank where he can execute iDEAL payments in his Internet banking environment. Within iDEAL, the Consumers' bank is called the Issuer. The Merchant has a relation with his bank in order to accept iDEAL payments. Within iDEAL, the Merchant's bank is referred to as the Acquirer. As stated in the introduction, this document will only cover the iDEAL messages that are exchanged between the Merchant and the Acquirer. However, the iDEAL messages that are exchanged between the Acquirer and the Issuer will be briefly explained if necessary to provide a good understanding of the entire iDEAL transaction.

Besides the four parties mentioned that are always involved in an iDEAL transaction, additional parties can be involved. The Merchant can, for example, use a Payment Service Provider (PSP) to establish the connection with its Acquiring bank. When this PSP receives/collects the payments before they are paid to the Merchant, this is called a "Collecting PSP" (CPSP). In this case the Collecting PSP acts as the Merchant for the purpose of the iDEAL payments and holds the iDEAL contract with the Acquiring bank on behalf of one or multiple other Merchants. Other roles related to iDEAL payments are out of scope for this document. (Other roles include Distributing PSPs (DPSPs) / Technical PSPs (TPSPs), which act as a software provider for the merchant and can provide a technical connection between merchant and Acquiring bank. They do not play a part in the payment process itself and do not have a contract with a bank and are therefore not included in the figure). The figure shows the parties in this model and their relations.

 

A demo of an iDEAL payment can be found online at https://www.ideal.nl/demo/en/. A typical iDEAL transaction comprises (request-/response-) XML messaging and browser redirects, which handle the initiation, and processing of the transaction in a particular sequence, with all parties involved being informed on the status of the transaction. 

The steps in this transaction are shown in the figure.

  • By using the Directory protocol the Merchant sends a DirectoryRequest to the Acquirer. This is a request in XML format to obtain the list of participating Consumer banks (Issuers) from the Acquirer. The Acquirer will provide this list back to the Merchant by sending back the DirectoryResponse. The Merchant will show the list of banks, which was sent in the DirectoryResponse to the Consumer. The Consumer will choose his bank from this list. The Directory protocol is explained in more detail in chapter 4.

  • By using the Payment protocol the Merchant sends a TransactionRequest to the Acquirer, containing the Issuer chosen by the Consumer, the amount, a purchase id and other transaction details. This message also contains the merchantReturnURL. This URL is used by the Issuer to redirect the Consumer back to the Merchant's website when he has completed the payment process. After the Acquirer has received the message from the Merchant, he sends a separate message to the Issuer that was selected by the Consumer. In return, the Issuer responds with a message that contains the issuerAuthenticationURL (and other data). The Acquirer passes this issuerAuthenticationURL together with a unique TransactionID back to the Merchant via the TransactionResponse message, which is the response to the TransactionRequest. The Merchant now redirects the Consumer to the issuerAuthenticationURL, which refers to the page of the Internet banking portal where the Issuer provides the appropriate prefilled iDEAL transaction details. The Consumer authorizes the payment and receives a confirmation from the Issuer. Then the Consumer is redirected back to the website of the Merchant via the merchantReturnURL. The entire Payment protocol and the 2 redirects are further described in chapter 5.

  • Finally the Merchant initiates the Query protocol by sending a StatusRequest message to the Acquirer. The Acquirer will request the transaction status, if necessary, from the appropriate Issuer and returns the status to the Merchant. If all steps in the transaction were successful this status message contains the proof of payment for the Merchant. Chapter 6 contains more detailed information on the Query protocol. Instead of a regular response to the messages mentioned above, it is also possible that an ErrorResponse is returned. This can be the case if the request contains an error, or if an error occurs during the processing of the request. The ErrorResponse messages are discussed in chapter 7.

 

The next chapter describes the general format of iDEAL messages. In subsequent chapters the three protocols are discussed in more detail.

The iDEAL Mobile transaction flow is almost identical to the transaction flow in a regular iDEAL transaction. The only difference is the redirect to the 'landing page' (using the issuerAuthenticationURL) where the Consumer, using a mobile device, is either directly sent to the mobile banking app or can choose to be redirected to the Issuer's (mobile) web page or to the Issuer's mobile banking app. 


3. Message format 

3.1 General

This chapter contains a description of the general message structure for the Directory protocol, the Payment protocol and the Query protocol. The subsequent sections will describe the specific fields within the XML messages for each protocol in more detail.

3.2 Header format

The following HTTP header is used for all messages:

Data element

Mandatory

Explanation

Data element

Mandatory

Explanation

Content-Type

Yes

Defines how the remainder of the content is to be interpreted. Contains the value: text/xml; charset="UTF-8".

  • All messages must comply with the HTTP 1.1 standard, as defined in RFC 2616 of W3C. For more information: http://www.w3.org/Protocols/rfc2616/rfc2616.html

  • Each XML request message must be sent as the body of a HTTP POST message.

  • Each XML response message must be sent as the body of a HTTP 200 OK message.

The following XML header is used for all messages:

Data element

Mandatory

Explanation

Data element

Mandatory

Explanation

Version

Yes

The XML version according to W3C: 1.0

Encoding

Yes

The character encoding used for (the content of) the XML: UTF-8



POST /nl/issuerInformation/getIssuerInformation.xml HTTP/1.1
Content-type: text/xml, charset="UTF-8"
Content-Length: 1201
Host: ideal.abnamro.nl


<?xml version="1.0" encoding="UTF-8"?>
<DirectoryReq
xmlns="http://www.idealdesk.com/ideal/messages/mer-acq/3.3.1" version="3.3.1">
<createDateTimestamp>2008-11-14T09:30:47.0Z</createDateTimestamp>
<Merchant>
.....


3.3 XML Namespace declaration

XML namespace declaration in iDEAL messages can be done in any way allowed by the XML standards (default namespace declaration or namespace qualification/prefixes).
Most of the example messages given in this document use the default method of namespace declaration. At the end of appendix B one example is given of a message with namespace prefixes. Both types of messages are valid and must be accepted.

3.4 Conventions for empty fields

In iDEAL an XML tag for an optional or conditional field is either:

  • present (in which case, the tag must be filled with a valid value)

  • or not present at all.

XML tags without content are not allowed and will result in an error message.

3.5 Merchant information registered with Acquirer

Besides the transaction information that the Merchant provides in the iDEAL messages described in the following chapters, the Acquirer also adds information to the iDEAL messages from its own records. Some of this information needs to be registered by a Merchant with the Acquirer before the Merchant can send in its first iDEAL transactions. The relevant iDEAL information is described below:

Data element

Merchant

Sub-element

Format

Description

legalName

AN..max70

The legal name of the Merchant as registered with the Acquirer. Used together with Merchant.tradeName to represent the Merchant (e.g. 'Merchant.legalName collecting for Merchant.tradeName'). Also used as a name for the Merchant.merchantIBAN for the transfer by the Issuer. It should be the same as the name of the bank account of the Merchant, as registered with the Acquirer.

tradeName

AN..max35

The trade name of the Merchant, as registered with the Acquirer in case it differs from the legalName.

merchantIBAN

ANS..max34

The IBAN of the Merchant, as registered with the Acquirer. (This is linked to Merchant.merchantID.)

merchantBIC

ANS..max11

The BIC of the bank where the Merchant's account is held

Merchant information registrered by the acquirer.

Notation

Meaning

Notation

Meaning

AN

The field can contain any alphanumeric characters. This is followed by a number that indicated the length (or maximum length) of the field.

ANS

The field can contain a restricted set of alphanumeric characters (letters and numbers only). This is followed by a number that indicated the length (or maximum length) of the field.

N

The field contains a numeric value. This is followed by a number that indicated the length (or maximum length) of the field.

PN

The field contains a padded numeric value. The contents are extended to the maximum length by leading zeros.

CL

Indicates a code list of allowed values (enumeration). Which values are allowed is always explained together with the field.

DT

Indicates a date-time field.Format yyyy-MM-ddTHH:mm:ss.SSSZ. (ISO standard 8601). The time used is 'universal time' UTC (formerly GMT), without daylight saving time. Example: 2009-12-28T13:59:59.393Z

RDT

Indicates a relative date-time field (ISO standard 8601). For example: PT10M equals 10 minutes.

DEC(#1,#2)

Indicates a decimal value with #1 being maximum total digits and #2 being maximum fraction digits. DEC(6,2) can be 1234.56 for example.



 


4. Directory protocol 

4.1 General

The Directory protocol allows a Merchant to fetch an up to date list of participating Issuers from his Acquirer, which can be presented to the Consumer. In case of changes in the list of Issuers, the Directory protocol will automatically take care of the update and make it visible in the Issuer lists of all Merchants.

It is not allowed to perform the Directory protocol for each transaction. Since the list of Issuers only changes occasionally, it is sufficient to execute the Directory protocol on a daily basis and check if the list has changed based on the directoryDateTimestamp. If the Issuer list has changed, the latest version has to be saved and used for any subsequent transaction. Acquirers will normally also inform all Merchants (e.g. by email) about changes in their Issuer list. The Directory protocol should at least be executed once a month.

The Directory protocol (like the Payment protocol and the Query protocol) consists of a HTTP POST request from the Merchant to the Acquirer, followed by a HTTP response. The DirectoryRequest is sent to the URL that is provided to the Merchant by the Acquirer for this specific purpose. This URL can be different from the one that is used for the TransactionRequest and the StatusRequest, but it can also be the same URL.

The Acquirer validates the authenticity of the message sent by the Merchant by verifying the signature in the message. In order to validate the Acquirer will need the Merchant's Certificate also containing the public key. The way in which the public part of the Merchant certificate is communicated with the Acquirer varies per bank. Please refer to chapter 8 for more information on authentication and security.

4.2 DirectoryRequest

The DirectoryRequest consists of an XML message that is sent to the Acquirer with HTTP POST (see chapter 3 for more information). The table below shows all fields and formatting of the DirectoryRequest. For legenda see 3.5.


Fields of the DirectoryRequest

Name

Description

Format

Name

Description

Format

createDateTimestamp

Date and time at which the directory request message was created.

DT

merchantID

MerchantID as supplied to the Merchant by the Acquirer. If the MerchantID has less than 9 digits, leading zeros must be used to fill out the field.

PN..9

subID

Merchant subID, as supplied to the Merchant by the Acquirer, if the Merchant has requested to use this. A Merchant can state a request to the Acquirer to use one or more subIDs. In this way apart from the Legal Name the Trade name will also be shown on the bank statements for each subID used. Unless agreed otherwise with the Acquirer, the Merchant has to use 0 (zero) as subID by default (if no subIDs are used).

N..max6

SignedInfo

This element contains information about the signature as described in W3C XMLdsig specifications

*

SignatureValue

Contains the electronic signature as described in W3C XMLdsig specifications.

*

KeyInfo

Contains information (fingerprint) about the certificate that is used for generating the digital signature, so the receiver can use the right public key for validating the signature as described in W3C XMLdsig specifications.

*

*SignedInfoSignatureValue and KeyInfo are XML Signature data elements that are defined in the XML-Signature Syntax and Processing. The signature is described in more detail in chapter 8. The XML Schema for XML Signatures is available from W3C at the following URL: http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd.

Example Message

<?xml version="1.0" encoding="UTF-8"?> <DirectoryReq xmlns="http://www.idealdesk.com/ideal/messages/mer-acq/3.3.1" version="3.3.1"> <createDateTimestamp>2008-11-14T09:30:47.0Z</createDateTimestamp> <Merchant> <merchantID>100000001</merchantID> <subID>1</subID> </Merchant> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> <!-- Signature is placed here. See Signature section for specification--> </Signature> </DirectoryReq>

4.3 DirectoryResponse

The Merchant will receive the DirectoryResponse as a reply to the DirectoryRequest. This XML message contains a list of Issuer names with their corresponding issuerID (BIC). Issuers are grouped by country. The banks in the Merchant's country of choice may be presented at the top in the Issuer selection list, the rest are sorted alphabetically by country, then by bank name. The table below shows all fields that appear in the DirectoryResponse message. For legenda see 3.5.

Fields of the DirectoryResponse

Name

Description

Format

Name

Description

Format

createDateTimestamp

Date and time at which the response message was created.

DT

acquirerID

Unique four-digit identifier of the Acquirer within iDEAL.

PN..4

directoryDateTimestamp

The date and time on which the Directory was updated by the Acquirer.

DT

countryNames

Contains the countryNames in the official languages of the country, separated by a '/' symbol (e.g. 'België/Belgique') Country names need only be displayed if there are banks from more than one country on the Issuer list. Currently, all banks in the list are from the Netherlands, so currently the country name can be omitted.



issuerID

Bank Identifier Code (BIC) of the iDEAL Issuer.

ANS..max11

issuerName

The name of the Issuer (as this should be displayed to the Consumer in the Merchant's Issuer list).

AN..max35

SignedInfo

This element contains information about the signature as described in W3C XMLdsig specifications

*

SignatureValue

Contains the electronic signature as described in W3C XMLdsig specifications.

*

KeyInfo

Contains information (fingerprint) about the certificate that is used for generating the digital signature, so the receiver can use the right public key for validating the signature as described in W3C XMLdsig specifications.

*

*SignedInfoSignatureValue and KeyInfo are XML Signature data elements that are defined in the XML-Signature Syntax and Processing. The signature is described in more detail in chapter 8. The XML Schema for XML Signatures is available from W3C at the following URL: http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd.

Example Message

<?xml version="1.0" encoding="UTF-8"?> <DirectoryRes xmlns="http://www.idealdesk.com/ideal/messages/mer-acq/3.3.1" version="3.3.1"> <createDateTimestamp>2008-11-14T09:30:47.0Z</createDateTimestamp> <Acquirer> <acquirerID>0001</acquirerID> </Acquirer> <Directory> <directoryDateTimestamp>2004-11-10T10:15:12.145Z</directoryDateTimestamp> <Country> <countryNames>Nederland</countryNames> <Issuer> <issuerID>ABNANL2AXXX</issuerID> <issuerName>ABN AMRO Bank</issuerName> </Issuer> <Issuer> <issuerID>INGBNL2AXXX</issuerID> <issuerName>ING</issuerName> </Issuer> <Issuer> <issuerID>RABONL2UXXX</issuerID> <issuerName>Rabobank</issuerName> </Issuer> </Country> </Directory> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> <!-- Signature is placed here. See Signature section for specification--> </Signature> </DirectoryRes>

4.4 Presentation of the Issuer selection list

To ensure that the Consumer experience of an iDEAL transaction is consistent and recognizable through all Merchant websites; all Merchants have to comply with certain presentation standards:

  • All Issuers in the DirectoryResponse (to be collected at least monthly) have to be shown in a list (e.g. dropdown list or list of radio buttons) in alphabetic order and exactly as presented in the DirectoryResponse message.

  • 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 a new Issuer, the Issuer list should be updated wihtin one month (preferably earlier).

  • It is recommended to configure the HTML "value" field of the items in the list box to be the issuerID (BIC) of the corresponding Issuer, because this value is used in subsequent messages (TransactionRequest).

  • The Merchant may preselect an Issuer 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.

An example of a correct presentation of the Issuer selection list is shown in the figure.

Example of possible Issuer list presentation method (in Dutch)

If a Merchant learns via the iDEAL Notification System (Central Reporting tool for iDEAL banks to state system non-availability) or via error messages received from the Acquiring bank that a particular Issuing bank is currently not available, the Merchant may display a message on its website informing Consumers that the particular bank is not available. In other words, it is perfectly permissible to display a message conveying such information but it is not permissible to temporarily remove or grey out the Issuing bank concerned from the Issuer selection list. 


5. Payment protocol 

5.1 General

The Payment protocol initiates the exchange of messages of the actual iDEAL payment initiation. After the Consumer has chosen iDEAL as a payment method and has selected his bank, the Merchant sends a TransactionRequest to the Acquirer. Within the iDEAL standards this message is referred to as the AcquirerTransactionRequest. The Acquirer replies to the TransactionRequest with a TransactionResponse. This TransactionResponse will also (among other fields) contain the issuerAuthenticationURL. This URL will redirect the browser of the Consumer to the Issuer in order to let him authorize the payment.

5.2 TransactionRequest

The XML message sent by the Merchant to the Acquirer to initiate the payment contains the fields shown in below table. For legenda see 3.5.


Fields of the TransactionRequest

Name

Description

Format

Name

Description

Format

createDateTimestamp

Date and time at which the TransactionRequest message was created.

DT

issuerID

The ID (BIC) of the Issuer selected by the Consumer, as stated in the Issuer list.

ANS..max11

merchantID

MerchantID as supplied to the Merchant by the Acquirer. If the MerchantID has less than 9 digits leading zeros are used to fill out the field.

PN..9

subID

Merchant subID, as supplied to the Merchant by the Acquirer, if the Merchant has requested to use this. A Merchant can state a request to the Acquirer to use one or more subIDs. In this way apart from the Legal Name the Trade name will also be shown on the bank statements for each subID used. Unless agreed otherwise with the Acquirer, the Merchant has to use 0 (zero) as subID by default (if no subIDs are used).

N..max6

merchantReturnURL

Valid Merchant URL (not necessarily beginning with http:// or https://) which must redirect the Consumer from the Issuer back to the Merchant website after authorisation of the transaction by the Consumer.

Example: https://www.webshop.nl/processpayment

Note that these URL’s may only contain URL-safe characters. All unsafe characters (space “<>#%{}|\^~[]) ’) must be properly encoded. Unencoded characters in the URL's do pass the message validation but can in some cases cause processing issues in the Issuing back-end, resulting in processing failures or failures in redirects back to merchants.

AN..max512

purchaseID

Unique identification of the order within the Merchant's system. This ID ultimately appears on the payment confirmation (Bank statement / account overview of the Consumer and Merchant).

ANS..max35

amount

The amount payable in euro (with a period (.) used as decimal separator).

DEC(12,2)

currency

Currency in which payment should be effected, expressed using the three-letter international currency code as per ISO 4217; Since iDEAL currently only supports Euro payments, value should always be 'EUR'.

ANS..3

expirationPeriod

Optional: the period of validity of the payment request as stated by the Merchant measured from the receipt by the Issuer. The Consumer must authorise the payment within this period. Otherwise the Issuer sets the status of the transaction to 'Expired'. Value period according to ISO 8601: PnYnMnDTnHnMnS. Minimum value:PT1M or PT60S (1 minute); maximum value: PT1H, PT60M or PT3600S (1 hour). If left blank by the Merchant the Issuer sets the default expirationPeriod to PT30M (thirty minutes). Since the majority of the successful payments are executed within fifteen minutes, it is recommended to set the expiration time to a maximum of PT15M. To accommodate the minimum time required for the Consumer to perform a transaction it is recommended to set the expirtation period not lower than three minutes (PT180S or PT3M).

RDT

language

This field enables the Issuer's site to select the Consumer's preferred language (e.g. the language selected on the Merchant's site), if the Issuer's site supports this. Code list in accordance with ISO 639-1. (Dutch = 'nl', English = 'en'). If a non-supported or non-existing language is entered the standard language of the Issuer is used. It is recommended to use 'nl' by default since not all Issuers support other languages.

CL AN..2

description

Description of the product(s) or services being paid for. This field must not contain characters that can lead to problems (for example those occurring in HTML editing codes). To prevent any possible errors most iDEAL systems will reject any description that contains HTML-tags and such other code.

AN..max35

entranceCode

The Transaction.entranceCode is an 'authentication identifier' to facilitate continuation of the session between Merchant and Consumer, even if the existing session has been lost. It enables the Merchant to recognise the Consumer associated with a (completed) transaction. The Transaction.entranceCode is sent to the Merchant in the Redirect. The Transaction.entranceCode must have a minimum variation of 1 million and should comprise letters and/or figures (maximum 40 positions). The Transaction.entranceCode is created by the Merchant and passed to the Issuer.

ANS..max40

SignedInfo

This element contains information about the signature as described in W3C XMLdsig specifications

*

SignatureValue

Contains the electronic signature as described in W3C XMLdsig specifications.

*

KeyInfo

Contains information (fingerprint) about the certificate that is used for generating the digital signature, so the receiver can use the right public key for validating the signature as described in W3C XMLdsig specifications.

*

*SignedInfoSignatureValue and KeyInfo are XML Signature data elements that are defined in the XML-Signature Syntax and Processing. The signature is described in more detail in chapter 8. The XML Schema for XML Signatures is available from W3C at the following URL: http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd.

Example Message

<?xml version="1.0" encoding="UTF-8"?> <AcquirerTrxReq xmlns="http://www.idealdesk.com/ideal/messages/mer-acq/3.3.1" version="3.3.1"> <createDateTimestamp>2008-11-14T09:30:47.0Z</createDateTimestamp> <Issuer> <issuerID>RABONL2UXXX</issuerID> </Issuer> <Merchant> <merchantID>100000001</merchantID> <subID>1</subID> <merchantReturnURL>https://www.ashop.eu/paymentHandling</merchantReturnURL> </Merchant> <Transaction> <purchaseID>iDEALaankoop21</purchaseID> <amount>59.99</amount> <currency>EUR</currency> <expirationPeriod>PT3M30S</expirationPeriod> <language>nl</language> <description>Documenten Suite</description> <entranceCode>4hd7TD9wRn76w6gGwGFDgdL7jEtb</entranceCode> </Transaction> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> <!-- Signature is placed here. See Signature section for specification--> </Signature> </AcquirerTrxReq>

5.3 TransactionResponse

If everything goes well the Acquirer will reply to the TransactionRequest with the TransactionResponse. The table below shows all fields of the TransactionResponse message. For legenda see 3.5.

Fields of the TransactionResponse

Name

Description

Format

Name

Description

Format

createDateTimestamp

Date and time at which TransactionResponse message was created.

DT

acquirerID

Unique four-digit identifier of the Acquirer within iDEAL.

PN..4

issuerAuthenticationURL

The complete Issuer URL to which the Consumer shall be redirected by the Merchant for authentication and authorisation of the transaction.

AN..max512

transactionID

Unique 16-digit number within iDEAL. The number consists of the acquirerID (first four positions) and a unique number generated by the Acquirer (12 positions). This ID ultimately appears on payment confirmation (bank statement or account overview of the Consumer and Merchant).

PN..16

transactionCreateDateTimestamp

Date and time at which the transaction was first registered by the Acquirer. This time can be used by Merchant, Acquiring bank and Issuing bank for reporting on the transaction.

DT

purchaseID

Unique identification of the order within the Merchant's system. This ID ultimately appears on the payment confirmation (Bank statement / account overview of the Consumer and Merchant). This field has the same value as in the TransactionRequest.

ANS..max35

SignedInfo

This element contains information about the signature as described in W3C XMLdsig specifications

*

SignatureValue

Contains the electronic signature as described in W3C XMLdsig specifications.

*

KeyInfo

Contains information (fingerprint) about the certificate that is used for generating the digital signature, so the receiver can use the right public key for validating the signature as described in W3C XMLdsig specifications.

*

*SignedInfoSignatureValue and KeyInfo are XML Signature data elements that are defined in the XML-Signature Syntax and Processing. The signature is described in more detail in chapter 8. The XML Schema for XML Signatures is available from W3C at the following URL: http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd.

Example Message

<?xml version="1.0" encoding="UTF-8"?> <AcquirerTrxRes xmlns="http://www.idealdesk.com/ideal/messages/mer-acq/3.3.1" version="3.3.1"> <createDateTimestamp>2008-11-14T09:30:47.0Z</createDateTimestamp> <Acquirer> <acquirerID>0001</acquirerID> </Acquirer> <Issuer> <issuerAuthenticationURL>https://www.issuingbank.eu/ideal?random=1Y98dHjPwe2qq3s&amp;amp;trxid=0001000000000001</issuerAuthenticationURL> </Issuer> <Transaction> <transactionID>0001000000000001</transactionID> <transactionCreateDateTimestamp>2008-11-14T09:30:50.125Z</transactionCreateDateTimestamp> <purchaseID>iDEAL21</purchaseID> </Transaction> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> <!-- Signature is placed here. See Signature section for specification--> </Signature> </AcquirerTrxRes>

5.4 Errors when executing Transaction Protocol

A number of errors may occur when executing the iDEAL Transaction Protocol. These may be related to unavailability within your own web store environment (Merchant), the Acquirer environment or the Issuer environment.
The following situations may occur:

  • The iDEAL payment cannot successfully be initiated.

  • You receive an error response (report 'X') from your Acquirer within the set time-out period.

  • You do not receive any response within the set time-out period.

In all of the above cases, the transaction protocol cannot be successfully executed. This means it is not possible for the iDEAL payment to take place at that time. In these cases, except when you received a consumermessage in the ErrorResponse, it is recommended that you display a message along the following lines to the Consumer: 'Unfortunately, it is not possible to pay using iDEAL at this time. Please try again later or use an alternative method of payment'. Or in Dutch:  'Op dit moment is betalen met iDEAL helaas niet mogelijk. Probeer het op een later moment nog eens of gebruik een andere betaalmethode'.

5.5 Redirect to the Internet banking environment (issuerAuthenticationURL)

After receiving the TransactionResponse the Merchant has to redirect the Consumer to the issuerAuthenticationURL of the selected Issuer bank, as stated in the TransactionResponse message. If the Merchant's page contains HTML frames, these will be removed by the Issuer ('frame busting'). If and when the Consumer returns to the Merchant's website (with the merchantReturnURL), the Merchant will have to completely rebuild its own page for showing the Merchant's order confirmation.
For privacy reasons it is not allowed to include any personal and order information of the Consumer in the HTTP referer header (contains information of the URL that the Consumer was redirected from) , when redirecting the Consumer to the chosen bank.

The Merchant needs to provide the redirect to the Issuer from the browser window or Merchant app where the Consumer selected the Issuing bank. If it is not possible to keep the Consumer in the same browser window then this should be communicated to the Consumer (e.g. 'You will now be redirected to the app or mobile website of your bank'). In case of a payment initiated in the Merchant app, it is not allowed to present the Issuer approval screens in a webview component within the Merchant's own app (in-app browser via webview). The complete payment flow, up to the redirect back to the Merchant's app, must take place in an app that is trusted by the Consumer, either the Consumer's chosen browser or the Issuer's mobile app. Thus, the issuerAuthenticationURL must, for execution, be offered to the operating system or opened with SafarViewController of Chrome Custom Tabs. For more information see paragraph 10.3. During the payment flow it must not be possible for the Consumer to initiate another payment through the Merchant's original app.

Relevant details about the redirect from the Merchant to the Issuer's mobile channel:

  • The Issuer decides which Consumers to redirect to which channel. For example some Issuers may treat users of tablet devices the same as mobile users while others will treat them like PC users;

  • The Merchant should not intervene with the redirect, there is only one issuerAuthenticationURL for the Merchant to use in all transactions, not a separate URL for mobile iDEAL transactions. The issuerAuthenticationURL should be executed by the operating system at all times;

  • If the Issuing bank has integrated iDEAL mobile in its mobile banking app, the Consumer is automatically directed to the mobile banking app or offered the option, on a 'landing page', to open the app or pay via the (mobile) web page. On this 'landing page' the Consumer might be offered the option to download the latest version of the mobile banking app, if it is not yet installed on the Consumer's device.

As mentioned above, an Issuer may allow the Consumer to download an (updated) mobile payment app as part of the transaction. In some cases, the extra time needed to download the app and personalise it may cause the payment to exceed the expiration period of the transaction if this is set to a very short interval. In such cases the payment cannot be completed successfully. The Merchant is able to collect the status of the transaction. 
In general, Merchants can avoid such failed transactions in the mobile channel by setting longer expiration periods for payments that are done from a Consumer's mobile device. This is also recommended because the bandwidth and signal strength available to mobile internet will often fluctuate, which can cause transactions on this channel to take longer to complete.

5.6 Redirect to the Merchant environment (merchantReturnURL)

After the Consumer has performed the necessary steps at the Issuer he will be presented with a 'Continue' button that must redirect him back to the website of the Merchant with the merchantReturnURL as supplied in the TransactionRequest.
Two GET parameters are appended to this URL: the entranceCode (see paragraph 5.2) with 'ec' as GET parameter name, and the transactionID (see paragraph 5.3) with 'trxid' as GET parameter name. It is also possible for a Merchant to add additional parameters. For example, if the Merchant defines the merchantReturnURL as follows:

http://www.webshop.nl/processpayment?producttype=electronics

the final URL will look something like:

http://www.webshop.nl/processpayment?producttype=electronics&trxid=0010123456789012&ec=4hd7TD9wRn76w 

The entranceCode field, as previously described in paragraph 5.2, should contain a unique value, with the object of preventing message 'sniffing'. Use of the same entranceCode each time would allow malevolent individuals to intercept the data from the merchantReturnURL and make fraudulent use of this information. This is why using unique values for the entranceCode is extremely important.

Note that a Consumer may not always use the redirect back to the Merchant environment that is offered by the Issuer. Also note that in exceptional cases the Issuer may be unable to match the transactionID in its system or another error occurs, which makes it impossible to redirect the Consumer back to the Merchant. In all other cases the Consumer is redirected with the parameters defined above, regardless of the final status of the payment (successful, cancelled, failed). The Merchant must then use the query protocol (see next chapter) to determine the status of the transaction.

After the Consumer has been authenticated in either the mobile or regular channel and has approved the payment, he is redirected back to the Merchant as normal (using the merchantReturnURL). The merchantReturnURL usually starts with 'https', redirecting the Consumer back to a page on the mobile device's browser. If the Consumer has initiated the payment from the Merchant's mobile app, the merchantReturnURL can be an app handler, which will redirect the Consumer directly to the Merchant app. An app handler is a call that can be used to start an app and request it to initiate a specific action. For example a Merchant's app handler can start with 'nl-companyname-ideal://' and this will open the Merchant's app. Also it is possible to make use of Universal Links (iOS) or Android App Links techniques to redirect the Consumer back to a Merchant app.

Note: the merchantReturnURL should always direct to a web page or app of the Merchant (or party acting on behalf of the Merchant).

5.7 Errors during execution of redirects

The following errors may occur during execution of the redirect to the online banking environment (Issuer), the execution of the payment at the Issuer and/or the redirect back to your (Merchant) environment:

  • The bank page is unavailable as a result of which the Consumer cannot pay, but neither can they be properly redirected to your confirmation page.

  • The bank page is available but the Consumer cannot (after paying or otherwise) be properly redirected to your confirmation page.

In both situations the Consumer cannot (as the result of a disturbance) return to your confirmation page in the normal way. In that case the Consumer can return to your website by using the 'back' button or entering the URL, for example. If the Consumer can be identified (for example because he or she has logged into the Merchant environment or via the browser session), the advice in these situations is to check the status of the payment and notify the Consumer of this.

If the Consumer can be identified and the status can be checked but is found to still be 'open', we recommend that the Consumer is shown the following message: We didn't receive a confirmation from your bank. When you see that your payment has been completed, we will deliver your order after we have received the payment. Or in Dutch: We hebben van uw bank nog geen bevestiging van uw betaling ontvangen. Als u in uw Internetbankieren ziet dat uw betaling heeft plaatsgevonden, zullen wij na ontvangst van de betaling tot levering overgaan.

If the Consumer cannot be identified, your system should check the status of the payment at the end of the expiration period. In such situations, we also recommend that the status of the payment is reported to the Consumer – as soon as it has become final – in one of the ways indicated below:

  • By e-mail.

  • On your website, for example in the account of the Consumer or via the Consumer's browser session.

5.8 Four different scenario's for completion of iDEAL Mobile payment

Four different scenario's that are possible in case of an iDEAL Mobile payment have been specified. There are four different scenarios possible because either the Issuer or the Merchant can both use a (mobile) web page or a mobile app.

Scenario

Merchant

Issuing Bank

Scenario

Merchant

Issuing Bank

1

(Mobile) web page

(Mobile) web page

2

(Mobile) web page

Mobile Banking App

3

Mobile app

Mobile Banking App

4

Mobile app

(Mobile) web page

Four different scenario’s for the completion of an iDEAL mobile payment



Step

Description

Scenario 1 - Merchant (mobile) web page to Issuer (mobile) web page

Scenario 2 - Merchant (mobile) web page to Issuer Mobile Banking App

Scenario 3 - Merchant mobile app to Issuer Mobile Banking App

Scenario 4 - Merchant mobile app  to Issuer (mobile) web page

Step

Description

Scenario 1 - Merchant (mobile) web page to Issuer (mobile) web page

Scenario 2 - Merchant (mobile) web page to Issuer Mobile Banking App

Scenario 3 - Merchant mobile app to Issuer Mobile Banking App

Scenario 4 - Merchant mobile app  to Issuer (mobile) web page

1

The Consumer selects the items to purchase, selects iDEAL as the payment method, selects his Issuing Bank.









2

The Consumer is redirected to the Issuer of his choice





It is mandatory for the Merchant to let the Operating System, which is installed on the Consumer's mobile device, handle the issuerAuthenticationURL or make use of the safe in-app browsing techniques SafarViewController and Chrome Custom Tabs. See paragraph 5.5 for more information.

3

The Issuer automatically leads the consumer to the mobile banking app (step 4 is then skipped) or presents the Issuer 'landing page' to the Consumer, which offers the option to complete the iDEAL payment in the Issuer's mobile banking app or in the Issuer's (mobile) web page.









4

The Consumer selects the (mobile) web page or the Issuer Mobile Banking app.









5

The Consumer is redirected to the Issuer's (mobile) web page or Mobile Banking app where he can log in and authorize the iDEAL payment. After completion of the payment the consumer is shown the result of the payment by the Issuer.







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