iDEAL Merchant Integration Guide (EN) (to be deprecated)
- Currence
Terms and conditions
Terms and conditions for provision of the iDEAL Merchant Integration Guide:
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.
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.
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.
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
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.
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 |
|---|---|---|
| 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 |
|---|---|---|
| Yes | The XML version according to W3C: 1.0 |
| Yes | The character encoding used for (the content of) the XML: UTF-8 |
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 |
| |
Sub-element | Format | Description |
| AN..max70 | The legal name of the Merchant as registered with the Acquirer. Used together with |
| AN..max35 | The trade name of the Merchant, as registered with the Acquirer in case it differs from the |
| ANS..max34 | The IBAN of the Merchant, as registered with the Acquirer. (This is linked to |
| ANS..max11 | The BIC of the bank where the Merchant's account is held |
Merchant information registrered by the acquirer.
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 |
|---|---|---|
| Date and time at which the directory request message was created. | DT |
| 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 |
| 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 |
| This element contains information about the signature as described in W3C XMLdsig specifications | * |
| Contains the electronic signature as described in W3C XMLdsig specifications. | * |
| 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. | * |
*SignedInfo, SignatureValue 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 |
|---|---|---|
| Date and time at which the response message was created. | DT |
| Unique four-digit identifier of the |