iDEAL version 3 Java reference implementation

According a writing of Rabobank to iDEAL Professional users, they are going to change the communication protocol of the popular iDEAL payment system. The latest version, v3.3.1 replaces iDEAL2 implementations. The changes are significant and Rabobank claims iDEAL v2 will no longer work on 1 august 2013.

For previous iDEAL versions, Rabobank provided an implementation of the iDEAL2 protocol as Java classes. This implementation example proved very helpful in integrating a webshop with the iDEAL payment system. For iDEAL3, Rabobank dropped this service. According to their help desk, the programming examples raised too many questions.

They do provide a formal document which describes the new communications. Some sections of this document are of excellent quality, some parts are not so good and even contain significant bugs leaving implementers in the dark.

Ishopservice provides this missing software layer. We implemented the protocol and supply it to the community. It is packed as a jar library as is very common in the Java world. The library deals with creation on the three types of messages an iDEAL implementation needs: directory, transaction and status. The library hides complexities such as XML message creation, XML digital signing and message and signature validation. It reduces iDEAL integration to three simple Java calls and an uniform handling of the results.

Example

Best way to show the simplicity is a code snippet. Below is an example of how to do a iDEAL directory request.

package nl.iShopService.ideal3.demo;
import java.util.List;

import nl.iShopService.ideal3.demo.util.Parameter;
import nl.iShopService.ideal3.generated.AcquirerErrorRes;
import nl.iShopService.ideal3.generated.Country;
import nl.iShopService.ideal3.generated.DirectoryRes;
import nl.iShopService.ideal3.generated.Issuer;
import nl.iShopService.util.Ideal3Http;
import nl.iShopService.util.Ideal3Messages;
import nl.iShopService.util.Signer;
import nl.iShopService.util.TypeIdeal3Request;

import org.apache.log4j.Logger;
import org.apache.log4j.PropertyConfigurator;

public class Directory {

	static final Logger logger = Logger.getLogger(Directory.class);
	public static void main(String[] args) {

		PropertyConfigurator.configure("log4j.properties");		
		
		logger.info("Make sure to adjust MERCHANT_ID and the KEYS in the Parameter.java file.");		
		
		String unsignedXml=Ideal3Messages.createDirectoryRequest( MERCHANT_ID, SUB);		// [1]	 		
		String signedXml=Signer.sign( unsignedXml, PRIVATE, CERTIFICATE_SHOP );			// [2]
		Ideal3Http ideal3Http=new Ideal3Http();		
		ideal3Http.send(signedXml,  testOrProductionUrl, TypeIdeal3Request.directory, CERTIFICATE_BANK);

		if( ideal3Http.isValidMessage() ){							// [3]

			if( ideal3Http.getDirectoryRes() != null ){					// [5]

				// Do your site integration here

				DirectoryRes directoryResponse = ideal3Http.getDirectoryRes();
				List countries = directoryResponse.getDirectory().getCountry();

				for( Country country : countries){

					List issuers = country.getIssuer();

					for( Issuer issuer : issuers){
						System.out.println(issuer.getIssuerName() );
					}
				}
			}

			if( ideal3Http.getAcquirerErrorRes() != null ){					// [4]
				AcquirerErrorRes acquirerErrorRes = ideal3Http.getAcquirerErrorRes();
				logger.warn(acquirerErrorRes.getError().getErrorCode());
			}
		}
		else{
			logger.error("Digital signature validation fails");
		}

	}
}

The four bold lines are of interest. The other lines are needed to provide a working example. This code performs an iDEAL directory request. The calls [ line 1 ] and [ 2 ] need a couple of parameters. The MERCHANT_ID is supplied by your bank.

The PRIVATE key and the CERTIFICATE_SHOP are generated by yourself. One can use the openssl utility to do this but the commands in the Rabobank documentation are NOT valid. IShopService provides the correct key generation commands.

Line[3 ] tests if the digital signature of the bank is valid, line [5] tests if the contents of your request is valid and from line [4] off, processing of your data can take place. The calls to the iDEAL Transaction and Status are done in a similar way.

If the iShopService iDEAL3 communication layer implementation meets your needs, feel free to contact us. We are happy to discuss the best possible solution for your case. We can also provide a solution for PHP, .NET or whatever language.

API Documentation