active_merchant_ideal 0.1.0

data/lib/active_merchant_ideal/ideal_response.rb

@@ -0,0 +1,219 @@
+require 'openssl'
+require 'base64'
+require 'rexml/document'
+
+module ActiveMerchant #:nodoc:
+  module Billing #:nodoc:
+    # The base class for all iDEAL response classes.
+    #
+    # Note that if the iDEAL system is under load it will _not_ allow more
+    # then two retries per request.
+    class IdealResponse < Response
+      def initialize(response_body, options = {})
+        @response = REXML::Document.new(response_body).root
+        @success = !error_occured?
+        @test = options[:test]
+      end
+
+      # Returns a technical error message.
+      def error_message
+        text('//Error/errorMessage') unless success?
+      end
+
+      # Returns a consumer friendly error message.
+      def consumer_error_message
+        text('//Error/consumerMessage') unless success?
+      end
+
+      # Returns details on the error if available.
+      def error_details
+        text('//Error/errorDetail') unless success?
+      end
+
+      # Returns an error type inflected from the first two characters of the
+      # error code. See error_code for a full list of errors.
+      #
+      # Error code to type mappings:
+      #
+      # * +IX+ - <tt>:xml</tt>
+      # * +SO+ - <tt>:system</tt>
+      # * +SE+ - <tt>:security</tt>
+      # * +BR+ - <tt>:value</tt>
+      # * +AP+ - <tt>:application</tt>
+      def error_type
+        unless success?
+          case error_code[0,2]
+          when 'IX' then :xml
+          when 'SO' then :system
+          when 'SE' then :security
+          when 'BR' then :value
+          when 'AP' then :application
+          end
+        end
+      end
+
+      # Returns the code of the error that occured.
+      #
+      # === Codes
+      #
+      # ==== IX: Invalid XML and all related problems
+      #
+      # Such as incorrect encoding, invalid version, or otherwise unreadable:
+      #
+      # * <tt>IX1000</tt> - Received XML not well-formed.
+      # * <tt>IX1100</tt> - Received XML not valid.
+      # * <tt>IX1200</tt> - Encoding type not UTF-8.
+      # * <tt>IX1300</tt> - XML version number invalid.
+      # * <tt>IX1400</tt> - Unknown message.
+      # * <tt>IX1500</tt> - Mandatory main value missing. (Merchant ID ?)
+      # * <tt>IX1600</tt> - Mandatory value missing.
+      #
+      # ==== SO: System maintenance or failure
+      #
+      # The errors that are communicated in the event of system maintenance or
+      # system failure. Also covers the situation where new requests are no
+      # longer being accepted but requests already submitted will be dealt with
+      # (until a certain time):
+      #
+      # * <tt>SO1000</tt> - Failure in system.
+      # * <tt>SO1200</tt> - System busy. Try again later.
+      # * <tt>SO1400</tt> - Unavailable due to maintenance.
+      #
+      # ==== SE: Security and authentication errors
+      #
+      # Incorrect authentication methods and expired certificates:
+      #
+      # * <tt>SE2000</tt> - Authentication error.
+      # * <tt>SE2100</tt> - Authentication method not supported.
+      # * <tt>SE2700</tt> - Invalid electronic signature.
+      #
+      # ==== BR: Field errors
+      #
+      # Extra information on incorrect fields:
+      #
+      # * <tt>BR1200</tt> - iDEAL version number invalid.
+      # * <tt>BR1210</tt> - Value contains non-permitted character.
+      # * <tt>BR1220</tt> - Value too long.
+      # * <tt>BR1230</tt> - Value too short.
+      # * <tt>BR1240</tt> - Value too high.
+      # * <tt>BR1250</tt> - Value too low.
+      # * <tt>BR1250</tt> - Unknown entry in list.
+      # * <tt>BR1270</tt> - Invalid date/time.
+      # * <tt>BR1280</tt> - Invalid URL.
+      #
+      # ==== AP: Application errors
+      #
+      # Errors relating to IDs, account numbers, time zones, transactions:
+      #
+      # * <tt>AP1000</tt> - Acquirer ID unknown.
+      # * <tt>AP1100</tt> - Merchant ID unknown.
+      # * <tt>AP1200</tt> - Issuer ID unknown.
+      # * <tt>AP1300</tt> - Sub ID unknown.
+      # * <tt>AP1500</tt> - Merchant ID not active.
+      # * <tt>AP2600</tt> - Transaction does not exist.
+      # * <tt>AP2620</tt> - Transaction already submitted.
+      # * <tt>AP2700</tt> - Bank account number not 11-proof.
+      # * <tt>AP2900</tt> - Selected currency not supported.
+      # * <tt>AP2910</tt> - Maximum amount exceeded. (Detailed record states the maximum amount).
+      # * <tt>AP2915</tt> - Amount too low. (Detailed record states the minimum amount).
+      # * <tt>AP2920</tt> - Please adjust expiration period. See suggested expiration period.
+      def error_code
+        text('//errorCode') unless success?
+      end
+
+      private
+
+      def error_occured?
+        @response.name == 'ErrorRes'
+      end
+
+      def text(path)
+        @response.get_text(path).to_s
+      end
+    end
+
+    # An instance of IdealTransactionResponse is returned from
+    # IdealGateway#setup_purchase which returns the service_url to where the
+    # user should be redirected to perform the transaction _and_ the
+    # transaction ID.
+    class IdealTransactionResponse < IdealResponse
+      # Returns the URL to the issuer’s page where the consumer should be
+      # redirected to in order to perform the payment.
+      def service_url
+        text('//issuerAuthenticationURL')
+      end
+
+      # Returns the transaction ID which is needed for requesting the status
+      # of a transaction. See IdealGateway#capture.
+      def transaction_id
+        text('//transactionID')
+      end
+
+      # Returns the <tt>:order_id</tt> for this transaction.
+      def order_id
+        text('//purchaseID')
+      end
+    end
+
+    # An instance of IdealStatusResponse is returned from IdealGateway#capture
+    # which returns whether or not the transaction that was started with
+    # IdealGateway#setup_purchase was successful.
+    #
+    # It takes care of checking if the message was authentic by verifying the
+    # the message and its signature against the iDEAL certificate.
+    #
+    # If success? returns +false+ because the authenticity wasn't verified
+    # there will be no error_code, error_message, and error_type. Use verified?
+    # to check if the authenticity has been verified.
+    class IdealStatusResponse < IdealResponse
+      def initialize(response_body, options = {})
+        super
+        @success = transaction_successful?
+      end
+
+      # Returns the status message, which is one of: <tt>:success</tt>,
+      # <tt>:cancelled</tt>, <tt>:expired</tt>, <tt>:open</tt>, or
+      # <tt>:failure</tt>.
+      def status
+        text('//status').downcase.to_sym
+      end
+
+      # Returns whether or not the authenticity of the message could be
+      # verified.
+      def verified?
+        @verified ||= IdealGateway.ideal_certificate.public_key.
+                        verify(OpenSSL::Digest::SHA1.new, signature, message)
+      end
+
+      private
+
+      # Checks if no errors occured _and_ if the message was authentic.
+      def transaction_successful?
+        !error_occured? && status == :success && verified?
+      end
+
+      # The message that we need to verify the authenticity.
+      def message
+        text('//createDateTimeStamp') + text('//transactionID') + text('//status') + text('//consumerAccountNumber')
+      end
+
+      def signature
+        Base64.decode64(text('//signatureValue'))
+      end
+    end
+
+    # An instance of IdealDirectoryResponse is returned from
+    # IdealGateway#issuers which returns the list of issuers available at the
+    # acquirer.
+    class IdealDirectoryResponse < IdealResponse
+      # Returns a list of issuers available at the acquirer.
+      #
+      #   gateway.issuers.list # => [{ :id => '1006', :name => 'ABN AMRO Bank' }]
+      def list
+        @response.get_elements('//Issuer').map do |issuer|
+          { :id => issuer.get_text('issuerID').to_s, :name => issuer.get_text('issuerName').to_s }
+        end
+      end
+    end
+  end
+end

data/lib/active_merchant_ideal.rb

@@ -0,0 +1,3 @@
+require 'active_merchant'
+require 'active_merchant_ideal/ideal.rb'
+require 'active_merchant_ideal/ideal_response.rb'

data/test/fixtures.yml

@@ -0,0 +1,12 @@
+# You can also paste the contents of the key and certificates here,
+# if you want to do so remove the “_file” part of the keys.
+ideal_ing_postbank:
+  test_url: https://idealtest.secure-ing.com:443/ideal/iDeal
+  merchant_id: ID
+  passphrase: PRIVATE KEY PASSPHRASE
+  private_key_file: |--
+    PASTE THE PATH TO YOUR PEM FILE HERE
+  private_certificate_file: |--
+    PASTE THE PATH TO YOUR CERTIFICATE FILE HERE
+  ideal_certificate_file: |--
+    PASTE THE PATH TO THE iDEAL CERTIFICATE FILE HERE

data/test/helper.rb

@@ -0,0 +1,143 @@
+require 'rubygems'
+require 'test/unit'
+require 'mocha'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'active_merchant_ideal'
+
+ActiveMerchant::Billing::Base.mode = :test
+
+# Test gateways
+class SimpleTestGateway < ActiveMerchant::Billing::Gateway
+end
+
+class SubclassGateway < SimpleTestGateway
+end
+
+class Hash #:nodoc:
+  # Return a new hash with all keys converted to symbols.
+  def symbolize_keys
+    inject({}) do |options, (key, value)|
+      options[(key.to_sym rescue key) || key] = value
+      options
+    end
+  end
+  # Destructively convert all keys to symbols.
+  def symbolize_keys!
+    self.replace(self.symbolize_keys)
+  end
+end
+
+module ActiveMerchant
+  module Assertions
+    def assert_field(field, value)
+      clean_backtrace do 
+        assert_equal value, @helper.fields[field]
+      end
+    end
+
+    # Allows the testing of you to check for negative assertions:
+    # 
+    #   # Instead of
+    #   assert !something_that_is_false
+    # 
+    #   # Do this
+    #   assert_false something_that_should_be_false
+    # 
+    # An optional +msg+ parameter is available to help you debug.
+    def assert_false(boolean, message = nil)
+      message = build_message message, '<?> is not false or nil.', boolean
+
+      clean_backtrace do
+        assert_block message do
+          not boolean
+        end
+      end
+    end
+
+    # A handy little assertion to check for a successful response:
+    # 
+    #   # Instead of
+    #   assert response.success?
+    # 
+    #   # DRY that up with
+    #   assert_success response
+    # 
+    # A message will automatically show the inspection of the response
+    # object if things go afoul.
+    def assert_success(response)
+      clean_backtrace do
+        assert response.success?, "Response failed: #{response.inspect}"
+      end
+    end
+
+    # The negative of +assert_success+
+    def assert_failure(response)
+      clean_backtrace do
+        assert_false response.success?, "Response expected to fail: #{response.inspect}"
+      end
+    end
+
+    def assert_valid(validateable)
+      clean_backtrace do
+        assert validateable.valid?, "Expected to be valid"
+      end
+    end
+
+    def assert_not_valid(validateable)
+      clean_backtrace do
+        assert_false validateable.valid?, "Expected to not be valid"
+      end
+    end
+
+    private
+    def clean_backtrace(&block)
+      yield
+    rescue Test::Unit::AssertionFailedError => e
+      path = File.expand_path(__FILE__)
+      raise Test::Unit::AssertionFailedError, e.message, e.backtrace.reject { |line| File.expand_path(line) =~ /#{path}/ }
+    end
+  end
+end
+
+
+module Test
+  module Unit
+    class TestCase
+      HOME_DIR = RUBY_PLATFORM =~ /mswin32/ ? ENV['HOMEPATH'] : ENV['HOME'] unless defined?(HOME_DIR)
+      LOCAL_CREDENTIALS = File.join(HOME_DIR.to_s, '.active_merchant/fixtures.yml') unless defined?(LOCAL_CREDENTIALS)
+      DEFAULT_CREDENTIALS = File.join(File.dirname(__FILE__), 'fixtures.yml') unless defined?(DEFAULT_CREDENTIALS)
+
+      include ActiveMerchant::Billing
+      include ActiveMerchant::Assertions
+
+      private
+
+      def all_fixtures
+        @@fixtures ||= load_fixtures
+      end
+
+      def fixtures(key)
+        data = all_fixtures[key] || raise(StandardError, "No fixture data was found for '#{key}'")
+
+        data.dup
+      end
+
+      def load_fixtures
+        file = File.exists?(LOCAL_CREDENTIALS) ? LOCAL_CREDENTIALS : DEFAULT_CREDENTIALS
+        yaml_data = YAML.load(File.read(file))
+        symbolize_keys(yaml_data)
+
+        yaml_data
+      end
+
+      def symbolize_keys(hash)
+        return unless hash.is_a?(Hash)
+
+        hash.symbolize_keys!
+        hash.each{|k,v| symbolize_keys(v)}
+      end
+    end
+  end
+end

data/test/remote_ideal_test.rb

@@ -0,0 +1,138 @@
+require File.dirname(__FILE__) + '/helper'
+
+class IdealTest < Test::Unit::TestCase
+  def setup
+    Base.mode = :test
+    setup_ideal_gateway(fixtures(:ideal_ing_postbank))
+
+    @gateway = IdealGateway.new
+
+    @valid_options = {
+      :issuer_id         => '0151',
+      :expiration_period => 'PT10M',
+      :return_url        => 'http://return_to.example.com',
+      :order_id          => '123456789012',
+      :currency          => 'EUR',
+      :description       => 'A classic Dutch windmill',
+      :entrance_code     => '1234'
+    }
+  end
+
+  def test_making_test_requests
+    assert @gateway.issuers.test?
+  end
+
+  def test_setup_purchase_with_valid_options
+    response = @gateway.setup_purchase(550, @valid_options)
+
+    assert_success response
+    assert_not_nil response.service_url
+    assert_not_nil response.transaction_id
+    assert_equal @valid_options[:order_id], response.order_id
+  end
+
+  def test_setup_purchase_with_invalid_amount
+    response = @gateway.setup_purchase(0.5, @valid_options)
+
+    assert_failure response
+    assert_equal "BR1210", response.error_code
+    assert_not_nil response.error_message
+    assert_not_nil response.consumer_error_message
+  end
+
+  # TODO: Should we raise a SecurityError instead of setting success to false?
+  def test_status_response_with_invalid_signature
+    IdealStatusResponse.any_instance.stubs(:signature).returns('db82/jpJRvKQKoiDvu33X0yoDAQpayJOaW2Y8zbR1qk1i3epvTXi+6g+QVBY93YzGv4w+Va+vL3uNmzyRjYsm2309d1CWFVsn5Mk24NLSvhYfwVHEpznyMqizALEVUNSoiSHRkZUDfXowBAyLT/tQVGbuUuBj+TKblY826nRa7U=')
+    response = capture_transaction(:success)
+
+    assert_failure response
+    assert !response.verified?
+  end
+
+  ###
+  #
+  # These are the 7 integration tests of ING which need to be ran sucessfuly
+  # _before_ you'll get access to the live environment.
+  #
+  # See test_transaction_id for info on how the remote tests are ran.
+  #
+
+  def test_retrieval_of_issuers
+    assert_equal [{ :id => '0151', :name => 'Issuer Simulator' }], @gateway.issuers.list
+  end
+
+  def test_successful_transaction
+    assert_success capture_transaction(:success)
+  end
+
+  def test_cancelled_transaction
+    captured_response = capture_transaction(:cancelled)
+
+    assert_failure captured_response
+    assert_equal :cancelled, captured_response.status
+  end
+
+  def test_expired_transaction
+    captured_response = capture_transaction(:expired)
+
+    assert_failure captured_response
+    assert_equal :expired, captured_response.status
+  end
+
+  def test_still_open_transaction
+    captured_response = capture_transaction(:open)
+
+    assert_failure captured_response
+    assert_equal :open, captured_response.status
+  end
+
+  def test_failed_transaction
+    captured_response = capture_transaction(:failure)
+
+    assert_failure captured_response
+    assert_equal :failure, captured_response.status
+  end
+
+  def test_internal_server_error
+    captured_response = capture_transaction(:server_error)
+
+    assert_failure captured_response
+    assert_equal 'SO1000', captured_response.error_code
+  end
+
+  private
+
+  # Shortcut method which does a #setup_purchase through #test_transaction and
+  # captures the resulting transaction and returns the capture response.
+  def capture_transaction(type)
+    @gateway.capture test_transaction(type).transaction_id
+  end
+
+  # Calls #setup_purchase with the amount corresponding to the named test and
+  # returns the response. Before returning an assertion will be ran to test
+  # whether or not the transaction was successful.
+  def test_transaction(type)
+    amount = case type
+    when :success      then 100
+    when :cancelled    then 200
+    when :expired      then 300
+    when :open         then 400
+    when :failure      then 500
+    when :server_error then 700
+    end
+
+    response = @gateway.setup_purchase(amount, @valid_options)
+    assert response.success?
+    response
+  end
+
+  # Setup the gateway by providing a hash of aatributes and values.
+  def setup_ideal_gateway(fixture)
+    fixture = fixture.dup
+    if passphrase = fixture.delete(:passphrase)
+      IdealGateway.passphrase = passphrase
+    end
+    fixture.each { |key, value| IdealGateway.send("#{key}=", value) }
+    IdealGateway.live_url = nil
+  end
+end