iDEAL

Library for the iDEAL payment standard.

What is iDEAL?

iDEAL is a set of standards developed to facilitate online payments through the online banking applications that most Dutch banks provide.

If a consumer already has online banking with ABN AMRO, Fortis, ING/Postbank, Rabobank, or SNS Bank, they can make payments using iDEAL in a way that they are already familiar with.

See http://ideal.nl and http://idealdesk.com for more information.

Merchant account

In order to use iDEAL you will need to get an iDEAL merchant account from your bank. Every bank offers ‘complete payment’ services, which can obfuscate the right choice. The payment product that you will want to get, in order to use this gateway class, is a bare bones iDEAL account.

• ING/Postbank: iDEAL Advanced
• ABN AMRO: iDEAL Zelfbouw
• Fortis: ? (Unknown)
• Rabobank: Rabo iDEAL Professional.
• SNS Bank: Not yet available

Note that this implementation was started a few years ago. As a result we only support version 2 or the iDEAL protocol, in some cases it might be necessary to configure this in your iDEAL backend or use a different set of API credentials.

Install

The iDEAL gem does not have any large external dependencies. It depends on Nap (a small HTTP library) and Builder (for building XML files). Because of these minor dependencies it’s suited to use in Ruby projects other than Ruby on Rails.

The easiest way to install is as a gem.

sudo gem install ideal

Or you can add it as a dependency in your Gemfile.

gem 'ideal'

Finally, if you don’t dig any of that gemming that’s so popular nowadays, you can install it as a plugin;

cd vendor/plugins
git clone --depth 1 git://github.com/Fingertips/Ideal.git ideal

Generate private keys and certificates

Messages between you and the acquirer are all signed in order to prove their authenticity. You will need a certificate for your side, this can be self-issued. If you like spending money, you can buy a certificate from some SSL authority. The certificate of the acquirer is probably hidden somewhere in plain sight in their documentation.

To create a self-signed certificate follow these steps:

• /usr/bin/openssl genrsa -des3 -out private_key.pem -passout pass:the_passphrase 1024
• /usr/bin/openssl req -x509 -new -key private_key.pem -passin pass:the_passphrase -days 3650 -out private_certificate.cer

Substitute the_passphrase with your own passphrase. You will need to configure that passphrase later on, so hand on to it.

You will need to upload your public key (certificate) to your iDEAL dashboard. Usually they have a completely independent test and live environment so you can use different certificates for both.

For more information on certificates and encryption see:

• http://en.wikipedia.org/wiki/Certificate_authority
• http://en.wikipedia.org/wiki/Self-signed_certificate

Test and activation

Once you’ve uploaded the certificate you need to initiate a number of transactions to complete the activation process. Luckily these transactions are part of the remote test for the gem. It’s still kind of a pain, but here we go!

git clone --depth 1 git://github.com/Fingertips/Ideal.git ideal
cd ideal
bundle install

• Create the ~/.ideal directory.
• Copy test/fixtures.yml to ~/.ideal.
• Fill in your own merchant id, passphrase and the correct locations to your private key and certificates.

ruby test/remote_test.rb

If you’ve succeeded you will see the following:

ruby test/remote_test.rb 
Loaded suite test/remote_test
Started
...........
Finished in 9.768389 seconds.

11 tests, 33 assertions, 0 failures, 0 errors

If you see test errors, you’re on your own (; You can run the test in debug mode to check what’s sent across the wire.

ruby -d test/remote_test.rb 

Dashboards

ING

• Test dashboard
• Live dashboard

ABN AMRO

• Test dashboard
• Live dashboard

Compatibility

We run continuous integration tests with Ruby 1.8.7, 1.9.2, and 1.9.3. We’re pretty sure that means it works (see the badge at the top of this file).

Example (Rails)

The following code was written as an example and should not be used without further testing in your application. USE AT YOUR OWN PERIL. Remember to have fun (;

Config

Configure the Gateway somewhere. One place could be config/initializers/ideal.rb.

unless Rails.env.production?
  Ideal::Gateway.environment = :test
end

# Other banks preloaded are :abnamro and :rabobank
Ideal::Gateway.acquirer = :ing 
Ideal::Gateway.merchant_id = '00123456789'

# Maybe you'd like another location
ideal_directory = Rails.root + 'config/ideal'
Ideal::Gateway.passphrase = 'the_passphrase'
Ideal::Gateway.private_key_file         = ideal_directory + 'private_key.pem'
Ideal::Gateway.private_certificate_file = ideal_directory + 'private_certificate.cer'
Ideal::Gateway.ideal_certificate_file   = ideal_directory + 'ideal.cer'

Show a payment form

Show a list of all issuers (banks) to choose from.

class PaymentsController < ActionController::Base
  def new
    @payment = Payment.new
    @issuers = sorted_issuers
  end
  
  private
  
  def ideal
    Ideal::Gateway.new
  end
  
  def sorted_issuers
    # NOTE: this does a GET on the bankend, you might want to memoize this
    ideal.issuers.list.sort_by do |issuer|
      issuer[:name]
    end.map do |issuer|
      [issuer[:name], issuer[:id]]
    end
  end
end

<%= form_for(@payment) do |f| %
  <%= f.select(:issuer_id, @issuers)
<% end %

Would result in something like:

ABN AMRO Bank Asr bank Postbank Rabobank Van Lanschot

Set up a payment

First you’ll need to setup a transaction and redirect the consumer there so she can make the payment:

class Payment < ActiveRecord::Base
  # Validation code used to validate returning notifications from iDeal
  def ideal_entrance_code
    Digest::SHA1.hexdigest("#{id}-#{created_at}-#{access_token}")
  end
  
  def ideal_attributes
    {
      # The customer has 30 minutes to complete the iDeal transaction (ISO 8601)
      :expiration_period => "PT30M",
      :issuer_id         => issuer_id,
      :return_url        => return_url,
      :order_id          => id.to_s,
      :description       => description,
      :entrance_code     => ideal_entrance_code
    }
  end
end

class PaymentsController < ActionController::Base
  def create
    payment = Payment.create(params[:payment].merge(
      :price_in_cents => 1000,                  # €10.00 in cents
      :return_url => payment_url(payment),      # This is where the customer will be returned to
      :description => 'A Dutch windmill'        # This will end up on the customer's bank statement (max 32 ASCII chars)
    ))
    
    response = ideal.setup_purchase(payment.price_in_cents, payment.ideal_attributes)
    if response.success?
      payment.transaction_id = response.transaction_id
      payment.status = 'pending'
      payment.save(false)
    else
      Rails.logger.info("Payment initialization failed: [#{response.error_message}] #{response.error_details}")
    end
    
    # Redirect the consumer to the issuer’s payment page.
    redirect_to response.service_url
  end
end

After the consumer is done with the payment she will be redirected to the :return_url. It’s now your responsibility as merchant to check if the payment has been made:

class PaymentsController < ActionController::Base
  def show
    @payment = Payment.find(params[:id])
    status = ideal.capture(@payment.transaction_id)
    if status.success?
      @payment.update_attributes!(:status => 'paid')
      flash[:notice] = "Congratulations, you are now the proud owner of a Dutch windmill!"
    end
  end
end

Help out!

If you find anything wrong with the gem, we would love to hear from you. Please create an issue with a patch if you run into anything.

History

In 2006 an iDEAL payment library was written in Ruby for a web shop build in Rails for selling mobile phone credits. It was basically a translation of the PHP example given by the iDEAL organization (see iDEAL Advanced Integration Manual PHP). Is was released as the ideal-on-rails library.

In 2007 this code was refactored as a patch for the ActiveMerchant library, this was mainly done by Fingertips for a client project. This patch was never accepted due to the fact it was too different (and maybe too obscure) from the ‘normal’ credit card gateways. After some lobbying an older patch of the code eventually found it’s way into ActiveMerchant.

In 2009 Fingertips forked the ActiveMerchant library and added an iDEAL gateway based on the ActiveMerchant path.

In 2010 this code was extracted and converted into a separate gem by Frank Oxener of Agile Dovadi, so it can be more easily used in combination with the latest version of ActiveMerchant. This library was just an extraction, nothing more and nothing less. There were no fundamental changes between the code from the ideal branch and the code of this gem. Later that year Sernin van de Krol added support for ABN AMRO.

At the end of 2011 Fingertips made yet another fork of the code as the iDeal gem. They ripped out all ActiveMerchant and Rails dependencies. In 2012 ABN AMRO switched their backend and support for this was also added.