buckaroo-ideal 0.0.1

data/lib/buckaroo-ideal.rb

@@ -0,0 +1,26 @@
+$LOAD_PATH << File.expand_path('..', __FILE__)
+
+module Buckaroo
+  module Ideal
+    # The banks that are supported by Buckaroo's iDEAL platform
+    BANKS = %w[ ABNAMRO  ASNBANK  FRIESLAND
+                INGBANK  RABOBANK SNSBANK
+                SNSREGIO TRIODOS  LANSCHOT  ]
+    
+    # The currencies that are supported by Buckaroo's iDEAL platform
+    CURRENCIES = %w[ EUR ]
+    
+    # The languages supported by Buckaroo's user interface:
+    LANGUAGES = %w[ NL EN DE FR ]
+    
+    autoload :VERSION,           'buckaroo-ideal/version'
+    autoload :Config,            'buckaroo-ideal/config'
+    autoload :Order,             'buckaroo-ideal/order'
+    autoload :Response,          'buckaroo-ideal/response'
+    autoload :ResponseSignature, 'buckaroo-ideal/response_signature'
+    autoload :RequestSignature,  'buckaroo-ideal/request_signature'
+    autoload :Request,           'buckaroo-ideal/request'
+    autoload :Status,            'buckaroo-ideal/status'
+    autoload :Util,              'buckaroo-ideal/util'
+  end
+end

data/lib/buckaroo-ideal/config.rb

@@ -0,0 +1,101 @@
+module Buckaroo
+  module Ideal
+    #
+    # Configuration singleton for storing settings required for making
+    # transactions.
+    #
+    class Config
+      class << self
+        # The gateway URL that is used to post form data to.
+        #
+        # @return [String] The gateway URL
+        attr_accessor :gateway_url
+        
+        # The merchant-key is supllied by Buckaroo. Every application MUST have
+        # it's own merchant key.
+        #
+        # @return [String] The merchant-key for the application
+        attr_accessor :merchant_key
+        
+        # The secret_key should only be known by your application and Buckaroo.
+        # It is used to sign orders and validate transactions.
+        #
+        # @return [String] The shared secret key that is used to sign
+        #   transaction requests
+        attr_accessor :secret_key
+        
+        # If test_mode is enabled, transactions will be registered by Buckaroo,
+        # but clients will not be forwared to the iDEAL page of their bank.
+        #
+        # Clients will be redirected back to the success_url of your application
+        #
+        # @return [Boolean] Test mode on/off
+        attr_accessor :test_mode
+        
+        # @return [String] The URL the user will be redirected to after a
+        #   successful transaction
+        attr_accessor :success_url
+        
+        # @return [String] The URL the user will be redirected to after a failed
+        #   transaction
+        attr_accessor :reject_url
+        
+        # @return [String] The URL the user will be redirected to after an error
+        #   occured during the transaction
+        attr_accessor :error_url
+        
+        # @return [String] The HTTP method that will be used to return the user
+        #   back to the application after a transaction
+        attr_accessor :return_method
+        
+        # There are 2 styles that you can use to integrate Buckaroo iDEAL:
+        # * POPUP - The transaction is performed in a popup
+        # * PAGE  - The transaction is performed in the original window
+        #
+        # @return [String] The style that is being used
+        attr_accessor :style
+        
+        # If the POPUP style is being used, you can autoclose the popup after
+        # a transaction. You will have to provide information about the
+        # transaction to the user on the page he will arrive on.
+        #
+        # @return [Boolean] Autoclose the popup after a transaction
+        attr_accessor :autoclose_popup
+        
+        # Default settings
+        def defaults
+          {
+            gateway_url:     'https://payment.buckaroo.nl/gateway/payment.asp',
+            merchant_key:    nil,
+            secret_key:      nil,
+            test_mode:       false,
+            success_url:     nil,
+            reject_url:      nil,
+            error_url:       nil,
+            return_method:   'POST',
+            style:           'PAGE',
+            autoclose_popup: false
+          }
+        end
+        
+        # Configure the integration with Buckaroo
+        def configure(settings = {})
+          defaults.merge(settings).each do |key, value|
+            set key, value
+          end
+        end
+        
+        # Reset the configuration to the default values
+        def reset
+          configure({})
+        end
+        
+        private
+        
+        def set(key, value)
+          instance_variable_set(:"@#{key}", value)
+        end
+      end
+    end
+  end
+end

data/lib/buckaroo-ideal/order.rb

@@ -0,0 +1,46 @@
+require 'active_support/core_ext/module/delegation'
+
+module Buckaroo
+  module Ideal
+    class Order
+      def self.defaults
+        { currency: 'EUR' }
+      end
+      
+      # @return [Float] The total amount that this order is for
+      attr_accessor :amount
+      
+      # @return [String] The currency that is being used for the transaction
+      attr_accessor :currency
+      
+      # @return [String] The bank that will be used for the order's transaction.
+      attr_accessor :bank
+      
+      # @return [String] The description for the transaction
+      attr_accessor :description
+      
+      # @return [String] The reference that will be passed to the response URLs
+      attr_accessor :reference
+      
+      # @return [String] The invoice number that is associated with the order
+      attr_accessor :invoice_number
+      
+      # Initialize a new +Order+ with the given settings. Uses the defaults from
+      # +Buckaroo::Ideal::Order.defaults+ for settings that are not specified.
+      #
+      # @return [Buckaroo::Ideal::Order] The +Order+ instance
+      def initialize(settings = {})
+        settings = self.class.defaults.merge(settings)
+        settings.each do |key, value|
+          set key, value
+        end
+      end
+      
+      private
+      
+      def set(key, value)
+        instance_variable_set(:"@#{key}", value)
+      end
+    end
+  end
+end

data/lib/buckaroo-ideal/request.rb

@@ -0,0 +1,164 @@
+require 'active_support/core_ext/module/delegation'
+
+module Buckaroo
+  module Ideal
+    #
+    # A class to help with the generation of payment forms for the Buckaroo
+    # Payment Gateway.
+    # 
+    # A form has a number of required parameters that are retreived from the
+    # +Buckaroo::Idea::Order+:
+    # * +currency+ -- required; but set by default to 'EUR'
+    # * +invoice_number+ -- required; not set by default
+    # * +amount+ -- required; this is the whole amount, it is automatically
+    #   converted to cents
+    # * +bank+ -- optional
+    # * +description+ -- optional
+    #
+    # It is possible to set the following options for this form:
+    # * +language+ -- required, defaults to 'NL'
+    # * +return_method+ -- required, defaults to +Buckaroo::Ideal::Config.return_method+
+    # * +style+ -- required, defaults to +Buckaroo::Ideal::Config.style+
+    # * +autoclose_popup+ -- required, defaults to +Buckaroo::Ideal::Config.autoclose_popup+
+    # * +reference+ -- optional
+    # * +success_url+ -- optional according to documentation
+    # * +reject_url+ -- optional
+    # * +error_url+ -- optional
+    #
+    # The +test_mode+, +gateway_url+ and +merchant_key+ are read from
+    # +Buckaroo::Ideal::Config+.
+    #
+    # To access the information required to create a form, instantiate a new
+    # +Buckaroo::Ideal::Request+ with an +Buckaroo::Ideal::Order+ instance:
+    #
+    #     order   = Buckaroo::Ideal::Order.new(amount: 100, invoice_number: 'EETNU-123')
+    #     request = Buckaroo::Ideal::Request.new(order)
+    #
+    # You can then use the information to create a form. An example in Rails:
+    #
+    #     <%= form_tag request.gateway_url do %>
+    #       <% request.parameters.each do |name, value| %>
+    #         <%= hidden_field_tag name, value %>
+    #       <% end %>
+    #       <%= submit_tag 'Proceed to payment' %>
+    #     <% end %>
+    class Request
+      def self.defaults
+        {
+          language:        'NL',
+          success_url:     Config.success_url,
+          reject_url:      Config.reject_url,
+          error_url:       Config.error_url,
+          return_method:   Config.return_method,
+          style:           Config.style,
+          autoclose_popup: Config.autoclose_popup
+        }
+      end
+      
+      # @return [String] The configured gateway_url in +Buckaroo::Ideal::Config+
+      delegate :gateway_url,  to: Config
+      
+      # @return [Boolean] The configured test_mode in +Buckaroo::Ideal::Config+
+      delegate :test_mode,    to: Config
+      
+      # @return [String] The configured merchant_key in +Buckaroo::Ideal::Config+
+      delegate :merchant_key, to: Config
+      
+      # @return [Buckaroo::Ideal::Order] The order for which the payment request
+      #   is being made
+      attr_reader :order
+      
+      # @return [String] The language in wich Buckaroo's user interface is
+      #   presented.
+      attr_accessor :language
+      
+      # Defaults to the configured +Buckaroo::Ideal::Config.success_url+, but
+      # can be overwritten in the +Order+ instance.
+      #
+      # @return [String] The URL the user will be redirected to after a
+      #   successful transaction
+      attr_accessor :success_url
+      
+      # Defaults to the configured +Buckaroo::Ideal::Config.reject_url+, but can
+      # be overwritten in the +Order+ instance.
+      #
+      # @return [String] The URL the user will be redirected to after a failed
+      #   transaction
+      attr_accessor :reject_url
+      
+      # Defaults to the configured +Buckaroo::Ideal::Config.error_url+, but can
+      # be overwritten in the +Order+ instance.
+      #
+      # @return [String] The URL the user will be redirected to after an error
+      #   occured during the transaction
+      attr_accessor :error_url
+      
+      # Defaults to the configured +Buckaroo::Ideal::Config.return_method+, but
+      # can be overwritten in the +Order+ instance.
+      #
+      # @return [String] The HTTP method that will be used to return the user
+      #   back to the application after a transaction
+      attr_accessor :return_method
+      
+      # Defaults to the configured +Buckaroo::Ideal::Config.style+, but can be
+      # overwritten in the +Order+ instance.
+      #
+      # @return [String] The style that is being used
+      attr_accessor :style
+      
+      # Defaults to the configured +Buckaroo::Ideal::Config.autoclose_popup+,
+      # but can be overwritten in the +Order+ instance.
+      #
+      # @return [Boolean] Autoclose the popup after a transaction
+      attr_accessor :autoclose_popup
+      
+      # Initialize a new +Buckaroo::Ideal::Request+ instance for the given
+      # order.
+      #
+      # @param [Buckaroo::Ideal::Order] The order that needs to be signed.
+      # @param [Hash] The settings for this form.
+      # @return [Buckaroo::Ideal::Request] The form for the order instance.
+      def initialize(order, settings = {})
+        @order = order
+        settings = self.class.defaults.merge(settings)
+        settings.each do |key, value|
+          set key, value
+        end
+      end
+      
+      def parameters
+        {
+          'BPE_Currency'        => order.currency,
+          'BPE_Invoice'         => order.invoice_number,
+          'BPE_Amount'          => to_cents(order.amount),
+          'BPE_Merchant'        => merchant_key,
+          'BPE_Language'        => language,
+          'BPE_Mode'            => to_numeric_boolean(test_mode),
+          'BPE_Return_Method'   => return_method,
+          'BPE_Style'           => style,
+          'BPE_Autoclose_Popup' => to_numeric_boolean(autoclose_popup),
+          'BPE_Signature2'      => signature
+        }.merge compact({
+          'BPE_Issuer'          => order.bank,
+          'BPE_Description'     => order.description,
+          'BPE_Reference'       => order.reference,
+          'BPE_Return_Success'  => success_url,
+          'BPE_Return_Reject'   => reject_url,
+          'BPE_Return_Error'    => error_url
+        })
+      end
+      
+      private
+      
+      def signature
+        RequestSignature.new(order).signature
+      end
+      
+      def set(key, value)
+        instance_variable_set(:"@#{key}", value)
+      end
+      
+      include Util
+    end
+  end
+end

data/lib/buckaroo-ideal/request_signature.rb

@@ -0,0 +1,74 @@
+require 'digest/md5'
+require 'active_support/core_ext/module/delegation'
+
+module Buckaroo
+  module Ideal
+    #
+    # Digital signature generator for +Buckaroo::Ideal::Order+ instances.
+    #
+    # A digital signature is used to sign your request so the Buckaroo Payment
+    # Service can validate that the request was made by your application.
+    #
+    # A digital signature is composed by generating a MD5 hash of the following
+    # values:
+    # * Merchant Key:  The +merchant_key+ that is provided by Buckaroo and set
+    #   in +Buckaroo::Ideal::Config+.
+    # * Invoice Number: The +invoice_number+ that is set in your
+    #   +Buckaroo::Ideal::Order+ instance.
+    # * Amount: The +amount+ that is set in your +Buckaroo::Ideal::Order+
+    #   instance in cents.
+    # * Currency: The +currency+ that is set in your +Buckaroo::Ideal::Order+
+    #   instance.
+    # * Mode: The +test_mode+ that is set in +Buckaroo::Ideal::Config+.
+    #
+    # To create a signature for an +Buckaroo::Ideal::Order+, instantiate a new
+    # +Buckaroo::Ideal::RequestSignature+ and provide the order:
+    #
+    #     order = Buckaroo::Ideal::Order.new(amount: 100, invoice_number: 'EETNU-123')
+    #     signature = Buckaroo::Ideal::Signature.new(order)
+    class RequestSignature
+      
+      # @return [Buckaroo::Ideal::Order] The order that is being signed.
+      attr_reader :order
+      
+      # @return [Boolean] The configured test_mode in +Buckaroo::Ideal::Config+
+      delegate :test_mode,    to: Config
+      
+      # @return [String] The configured merchant_key in +Buckaroo::Ideal::Config+
+      delegate :merchant_key, to: Config
+      
+      # @return [String] The configured secret_key in +Buckaroo::Ideal::Config+
+      delegate :secret_key,   to: Config
+      
+      # Initialize a new +Buckaroo::Ideal::Signature+ instance for the given
+      # order.
+      #
+      # @param [Buckaroo::Ideal::Order] The order that needs to be signed.
+      # @param [String] The secret key that is used to sign the order.
+      #   Defaults to the configured +Buckaroo::Ideal::Config.secret_key+.
+      # @return [Buckaroo::Ideal::Signature] The signature for the order
+      #   instance.
+      def initialize(order)
+        @order  = order
+      end
+      
+      def signature
+        salt = [
+          merchant_key,
+          to_normalized_string(order.invoice_number),
+          to_cents(order.amount),
+          order.currency,
+          to_numeric_boolean(test_mode),
+          secret_key
+        ].join
+        
+        Digest::MD5.hexdigest(salt)
+      end
+      alias_method :to_s, :signature
+      
+      private
+      
+      include Util
+    end
+  end
+end

data/lib/buckaroo-ideal/response.rb

@@ -0,0 +1,68 @@
+require 'active_support/core_ext/module/delegation'
+require 'time'
+
+module Buckaroo
+  module Ideal
+    class Response
+      # @return [Hash] The raw parameters that form the heart of the response
+      attr_reader :parameters
+      
+      # @return [String] The unique code that is given to the transaction by
+      #   Buckaroo's Payment Gateway
+      attr_reader :transaction_id
+      
+      # @return [Buckaroo::Ideal::Status] The status of the transaction
+      attr_reader :status
+      
+      # @return [String] The reference that was given to the
+      #   +Buckaroo::Ideal::Order+
+      attr_reader :reference
+      
+      # @return [String] The invoice_number that was given to the
+      #   +Buckaroo::Ideal::Order+
+      attr_reader :invoice_number
+      
+      # @return [Buckaroo::Ideal::ResponseSignature] The signature of the
+      #   transaction, which can be used to validate it's authenticity.
+      attr_reader :signature
+      
+      # @return [String] The currency that was used during the transaction
+      attr_reader :currency
+      
+      # @return [Time] The date and time of the transaction
+      attr_reader :time
+      
+      # @return [String] The timestamp of the transaction
+      attr_reader :timestamp
+      
+      # @return [Float] The amount that was transferred during the transaction
+      attr_reader :amount
+      
+      # @return [Boolean] Returns +true+ if the transaction was a test, +false+
+      #   if it was real
+      attr_reader :test_mode
+      
+      def initialize(params = {})
+        @parameters     = params
+        @transaction_id = parameters['bpe_trx']
+        @reference      = parameters['bpe_reference']
+        @invoice_number = parameters['bpe_invoice']
+        @currency       = parameters['bpe_currency']
+        @timestamp      = parameters['bpe_timestamp']
+        @time           = Time.parse(timestamp)
+        @amount         = from_cents(parameters['bpe_amount'])
+        @test_mode      = from_numeric_boolean(parameters['bpe_mode'])
+        @status         = Status.new(parameters['bpe_result'])
+        @signature      = ResponseSignature.new(self, parameters['bpe_signature2'])
+      end
+      
+      def valid?
+        signature.valid?
+      end
+      
+      private
+      
+      include Util
+    end
+  end
+end