mattbauer-activemerchant 1.4.2

data/lib/active_merchant/billing/gateways/moneris.rb

@@ -0,0 +1,295 @@
+require 'rexml/document'
+
+module ActiveMerchant #:nodoc:
+  module Billing #:nodoc:
+
+    # To learn more about the Moneris gateway, please contact 
+    # eselectplus@moneris.com for a copy of their integration guide. For 
+    # information on remote testing, please see "Test Environment Penny Value 
+    # Response Table", and "Test Environment eFraud (AVS and CVD) Penny 
+    # Response Values", available at Moneris' {eSelect Plus Documentation 
+    # Centre}[https://www3.moneris.com/connect/en/documents/index.html].
+    class MonerisGateway < Gateway
+      TEST_URL = 'https://esqa.moneris.com/gateway2/servlet/MpgRequest'
+      LIVE_URL = 'https://www3.moneris.com/gateway2/servlet/MpgRequest'
+      
+      self.supported_countries = ['CA']
+      self.supported_cardtypes = [:visa, :master, :american_express]
+      self.homepage_url = 'http://www.moneris.com/'
+      self.display_name = 'Moneris'
+  
+      # login is your Store ID
+      # password is your API Token
+      def initialize(options = {})
+        requires!(options, :login, :password)
+        @options = { :crypt_type => 7 }.update(options)
+        super      
+      end      
+    
+      # Referred to as "PreAuth" in the Moneris integration guide, this action 
+      # verifies and locks funds on a customer's card, which then must be 
+      # captured at a later date.
+      # 
+      # Pass in +order_id+ and optionally a +customer+ parameter.
+      def authorize(money, creditcard, options = {})
+        debit_commit 'preauth', money, creditcard, options        
+      end
+      
+      # This action verifies funding on a customer's card, and readies them for 
+      # deposit in a merchant's account.
+      # 
+      # Pass in <tt>order_id</tt> and optionally a <tt>customer</tt> parameter
+      def purchase(money, creditcard, options = {})
+        debit_commit 'purchase', money, creditcard, options
+      end
+     
+      # This action create a recurring purchase on a customer's card with the
+      # desired interval, frequency, limit, starting date.  It can also peform
+      # an immediate verification of funding on a customer's card and ready them
+      # for deposit in a merchant's account.  This immediate amount can differ from
+      # the recurring amount
+      #
+      # ==== Parameters
+      #
+      # * <tt>money</tt> -- The amount to be purchased. Either an Integer value in cents or a Money object.
+      # * <tt>creditcard</tt> -- The CreditCard details for the transaction.
+      # * <tt>:interval</tt> - :day, :week, or :month
+      # * <tt>:frequency</tt> - The number of intervals you wish to pass between billing cycles
+      # * <tt>:limit</tt> - The number of times to recur this transaction
+      # * <tt>:starts_on</tt> - This is the date on which the first charge will be billed.  The value must be in the 
+      # future.  It cannot be the day on which the transaction is being sent.  If the 
+      # transaction is to be billed immediately the start_now feature must be set to true 
+      # and the start_date should be set at the desired interval after today. 
+      # * <tt>:start_now</tt> - When a charge is to be made against the card immediately start_now should be 
+      # set to ‘true’.  If the billing is to start in the future then this value is to be set to 
+      # ‘false’.  When start_now is set to ‘true’ the amount to be billed immediately may 
+      # differ from the recur amount billed on a regular basis thereafter.
+      # * <tt>options</tt> -- A hash of optional parameters. Set :recur_amount to either an Integer
+      # value in cents or a Money object to have the recurring amount differ from the immediate amount.  Note 
+      # this only works if start_now is set to false.  Otherwise it is ignored.
+      def recurring_purchase(money, creditcard, interval, frequency, limit, starts_on, start_now, options = {})
+        requires!(options, :order_id)
+        params = debit_params(money, creditcard, options)
+        recur_params = {
+          :recur_unit => interval,
+          :start_now => start_now,
+          :start_date => starts_on,
+          :num_recurs => limit,
+          :period => frequency,
+          :recur_amount => amount(options[:recurring_money] || money)
+        }
+        commit('purchase', params, recur_params)
+      end      
+
+      # This action updates a recurring purchase on a customer's card. It requires
+      # the authorization code and can change the following: customer id, add more
+      # recurring payments, the total number of recurring payments, terminate
+      # the recurring payments, put them on hold (suspend), the amount and change 
+      # the credit card.
+      #
+      # ==== Parameters
+      #
+      # * <tt>authorization</tt> -- The authorization code used to initially create the recurring payment
+      # * <tt>options</tt> -- The possible options are:
+      # <Tt>:customer</tt> - the customer id to use
+      # <Tt>:extend_limit</tt> - add additional recurring payments
+      # <Tt>:limit</tt> - change the total number of recurring payments
+      # <Tt>:recurring_money</tt> - change the recurring payment amount
+      # <Tt>:terminate</tt> - set to true to stop recurring payments
+      # <Tt>:hold</tt> - set to true to hold recurring payments (suspend them)
+      # <Tt>:creditcard</tt> - a credit card object to associated with the recurring payments
+      def recurring_update(authorization, options = {})
+        params = {
+          :order_id   => split_authorization(authorization).last,
+          :cust_id    => options[:customer],
+          :add_num_recurs   => options[:extend_limit],
+          :total_num_recurs   => options[:limit],
+          :recur_amount => amount(options[:recurring_money]),
+          :terminate    => options[:terminate].nil? ? false : options[:terminate],
+          :hold    => options[:hold].nil? ? false : options[:hold]
+        }
+        if options[:creditcard]
+          params.merge!(
+            :pan        => options[:creditcard].number,
+            :expdate    => expdate(options[:creditcard])
+          )
+        end
+        commit 'recur_update', params
+      end  
+      
+      # This method retrieves locked funds from a customer's account (from a 
+      # PreAuth) and prepares them for deposit in a merchant's account.
+      # 
+      # Note: Moneris requires both the order_id and the transaction number of
+      # the original authorization.  To maintain the same interface as the other
+      # gateways the two numbers are concatenated together with a ; separator as
+      # the authorization number returned by authorization
+      def capture(money, authorization, options = {})
+        commit 'completion', crediting_params(authorization, :comp_amount => amount(money))
+      end
+
+      # Voiding requires the original transaction ID and order ID of some open 
+      # transaction. Closed transactions must be refunded. Note that the only 
+      # methods which may be voided are +capture+ and +purchase+.
+      # 
+      # Concatenate your transaction number and order_id by using a semicolon 
+      # (';'). This is to keep the Moneris interface consistent with other 
+      # gateways. (See +capture+ for details.)
+      def void(authorization, options = {})
+        commit 'purchasecorrection', crediting_params(authorization)
+      end
+      
+      # Performs a refund. This method requires that the original transaction 
+      # number and order number be included. Concatenate your transaction 
+      # number and order_id by using a semicolon (';'). This is to keep the 
+      # Moneris interface consistent with other gateways. (See +capture+ for 
+      # details.)
+      def credit(money, authorization, options = {})
+        commit 'refund', crediting_params(authorization, :amount => amount(money))
+      end
+   
+    private # :nodoc: all
+    
+      def expdate(creditcard)
+        sprintf("%.4i", creditcard.year)[-2..-1] + sprintf("%.2i", creditcard.month)
+      end
+      
+      def debit_commit(commit_type, money, creditcard, options)
+        requires!(options, :order_id)
+        commit(commit_type, debit_params(money, creditcard, options))
+      end
+      
+      # Common params used amongst the +purchase+ and +authorization+ methods
+      def debit_params(money, creditcard, options = {})
+        {
+          :order_id   => options[:order_id],
+          :cust_id    => options[:customer],
+          :amount     => amount(money),
+          :pan        => creditcard.number,
+          :expdate    => expdate(creditcard),
+          :crypt_type => options[:crypt_type] || @options[:crypt_type]
+        }
+      end
+      
+      # Common params used amongst the +credit+, +void+ and +capture+ methods
+      def crediting_params(authorization, options = {})
+        {
+          :txn_number => split_authorization(authorization).first, 
+          :order_id   => split_authorization(authorization).last, 
+          :crypt_type => options[:crypt_type] || @options[:crypt_type]
+        }.merge(options)
+      end
+      
+      # Splits an +authorization+ param and retrives the order id and 
+      # transaction number in that order.
+      def split_authorization(authorization)
+        if authorization.nil? || authorization.empty? || authorization !~ /;/
+          raise ArgumentError, 'You must include a valid authorization code (e.g. "1234;567")' 
+        else
+          authorization.split(';')
+        end
+      end
+  
+      def commit(action, parameters = {}, recurring_parameters = nil)
+        response = parse(ssl_post(test? ? TEST_URL : LIVE_URL, post_data(action, parameters, recurring_parameters)))
+
+        Response.new(successful?(response), message_from(response[:message]), response,
+          :test          => test?,
+          :authorization => authorization_from(response)
+        )
+      end
+      
+      # Generates a Moneris authorization string of the form 'trans_id;receipt_id'.
+      def authorization_from(response = {})
+        if response[:trans_id] && response[:receipt_id]
+          "#{response[:trans_id]};#{response[:receipt_id]}"
+        end
+      end
+      
+      # Tests for a successful response from Moneris' servers
+      def successful?(response)
+        successful_action?(response) || successful_recurring?(response)
+      end
+        
+      def successful_action?(response)
+        response[:response_code] && 
+        response[:complete] && 
+        (0..49).include?(response[:response_code].to_i)
+      end
+      
+      def successful_recurring?(response)
+        response[:recur_success]
+      end
+                                               
+      def parse(xml)
+        response = { :message => "Global Error Receipt", :complete => false }
+        hashify_xml!(xml, response)
+        response
+      end
+      
+      def hashify_xml!(xml, response)
+        xml = REXML::Document.new(xml)
+        return if xml.root.nil?
+        xml.elements.each('//receipt/*') do |node|
+          response[node.name.underscore.to_sym] = normalize(node.text)
+        end
+      end
+
+      def post_data(action, parameters = {}, recurring_parameters = nil)
+        xml   = REXML::Document.new
+        root  = xml.add_element("request")
+        root.add_element("store_id").text  = options[:login]
+        root.add_element("api_token").text = options[:password]
+        transaction = root.add_element(action)
+
+        # Must add the elements in the correct order
+        actions[action].each do |key|
+          transaction.add_element(key.to_s).text = parameters[key] unless parameters[key].blank?
+        end
+
+        if recurring_parameters
+          recur = transaction.add_element('recur')
+          actions['recur'].each do |key|
+            recur.add_element(key.to_s).text = recurring_parameters[key] unless recurring_parameters[key].blank?
+          end
+        end
+        xml.to_s
+      end
+    
+      def message_from(message)
+        return 'Unspecified error' if message.blank?
+        message.gsub(/[^\w]/, ' ').split.join(" ").capitalize
+      end
+
+      # Make a Ruby type out of the response string
+      def normalize(field)
+        case field
+          when "true"     then true
+          when "false"    then false
+          when '', "null" then nil
+          else field
+        end        
+      end
+      
+      def actions
+        {
+          "purchase"           => [:order_id, :cust_id, :amount, :pan, :expdate, :crypt_type],
+          "preauth"            => [:order_id, :cust_id, :amount, :pan, :expdate, :crypt_type],
+          "command"            => [:order_id],
+          "refund"             => [:order_id, :amount, :txn_number, :crypt_type],
+          "indrefund"          => [:order_id, :cust_id, :amount, :pan, :expdate, :crypt_type],
+          "completion"         => [:order_id, :comp_amount, :txn_number, :crypt_type],
+          "purchasecorrection" => [:order_id, :txn_number, :crypt_type],
+          "cavvpurcha"         => [:order_id, :cust_id, :amount, :pan, :expdate, :cav],
+          "cavvpreaut"         => [:order_id, :cust_id, :amount, :pan, :expdate, :cavv],
+          "transact"           => [:order_id, :cust_id, :amount, :pan, :expdate, :crypt_type],
+          "Batchcloseall"      => [],
+          "opentotals"         => [:ecr_number],
+          "batchclose"         => [:ecr_number],
+          "recur"              => [:recur_unit, :start_now, :start_date, :num_recurs, :period, :recur_amount],
+          "recur_update"       => [:order_id, :cust_id, :recur_amount, :pan, :expdate, :add_num_recurs,  :total_num_recurs, :hold, :terminate]
+        }
+      end
+    end
+  end
+end

data/lib/active_merchant/billing/gateways/moneris_usa.rb

@@ -0,0 +1,258 @@
+require 'rexml/document'
+
+module ActiveMerchant #:nodoc:
+  module Billing #:nodoc:
+
+    # To learn more about the Moneris USA gateway, please contact 
+    # eselectplus@moneris.com for a copy of their integration guide. For 
+    # information on remote testing, please see "Test Environment Penny Value 
+    # Response Table", and "Test Environment eFraud (AVS and CVD) Penny 
+    # Response Values", available at Moneris' {eSelect Plus Documentation}
+    # [https://esplusqa.moneris.com/connect/en/documents/index.html].
+    class MonerisUsaGateway < Gateway
+      TEST_URL = 'https://esplusqa.moneris.com/gateway_us/servlet/MpgRequest'
+      LIVE_URL = 'https://esplus.moneris.com/gateway_us/servlet/MpgRequest'
+      
+      self.supported_countries = ['US']
+      self.supported_cardtypes = [:visa, :master, :american_express, :discover]
+      self.homepage_url = 'http://www.monerisusa.com/'
+      self.display_name = 'Moneris USA'
+      
+      # login is your Store ID
+      # password is your API Token
+      def initialize(options = {})
+        requires!(options, :login, :password)
+        @options = { :crypt_type => 7 }.update(options)
+        super      
+      end      
+
+      # Referred to as "PreAuth" in the Moneris integration guide, this action 
+      # verifies and locks funds on a customer's card, which then must be 
+      # captured at a later date.
+      # 
+      # Pass in +order_id+ and optionally a +customer+ parameter.
+      def authorize(money, creditcard, options = {})
+        debit_commit 'us_preauth', money, creditcard, options        
+      end
+
+      # This action verifies funding on a customer's card, and readies them for 
+      # deposit in a merchant's account.
+      # 
+      # Pass in <tt>order_id</tt> and optionally a <tt>customer</tt> parameter
+      def purchase(money, creditcard, options = {})
+        debit_commit 'us_purchase', money, creditcard, options
+      end
+
+      # This method retrieves locked funds from a customer's account (from a 
+      # PreAuth) and prepares them for deposit in a merchant's account.
+      # 
+      # Note: Moneris requires both the order_id and the transaction number of
+      # the original authorization.  To maintain the same interface as the other
+      # gateways the two numbers are concatenated together with a ; separator as
+      # the authorization number returned by authorization
+      def capture(money, authorization, options = {})
+        commit 'us_completion', crediting_params(authorization, :comp_amount => amount(money))
+      end
+
+      # Voiding requires the original transaction ID and order ID of some open 
+      # transaction. Closed transactions must be refunded. Note that the only 
+      # methods which may be voided are +capture+ and +purchase+.
+      # 
+      # Concatenate your transaction number and order_id by using a semicolon 
+      # (';'). This is to keep the Moneris interface consistent with other 
+      # gateways. (See +capture+ for details.)
+      def void(authorization, options = {})
+        commit 'us_purchasecorrection', crediting_params(authorization)
+      end
+
+      # Performs a refund. This method requires that the original transaction 
+      # number and order number be included. Concatenate your transaction 
+      # number and order_id by using a semicolon (';'). This is to keep the 
+      # Moneris interface consistent with other gateways. (See +capture+ for 
+      # details.)
+      def credit(money, authorization, options = {})
+        commit 'us_refund', crediting_params(authorization, :amount => amount(money))
+      end
+      
+      # This action create a recurring purchase on a customer's card with the
+      # desired interval, frequency, limit, starting date.  It can also peform
+      # an immediate verification of funding on a customer's card and ready them
+      # for deposit in a merchant's account.  This immediate amount can differ from
+      # the recurring amount
+      #
+      # ==== Parameters
+      #
+      # * <tt>money</tt> -- The amount to be purchased. Either an Integer value in cents or a Money object.
+      # * <tt>creditcard</tt> -- The CreditCard details for the transaction.
+      # * <tt>:interval</tt> - :day, :week, or :month
+      # * <tt>:frequency</tt> - The number of intervals you wish to pass between billing cycles
+      # * <tt>:limit</tt> - The number of times to recur this transaction
+      # * <tt>:starts_on</tt> - This is the date on which the first charge will be billed.  The value must be in the 
+      # future.  It cannot be the day on which the transaction is being sent.  If the 
+      # transaction is to be billed immediately the start_now feature must be set to true 
+      # and the start_date should be set at the desired interval after today. 
+      # * <tt>:start_now</tt> - When a charge is to be made against the card immediately start_now should be 
+      # set to ‘true’.  If the billing is to start in the future then this value is to be set to 
+      # ‘false’.  When start_now is set to ‘true’ the amount to be billed immediately may 
+      # differ from the recur amount billed on a regular basis thereafter.
+      # * <tt>options</tt> -- A hash of optional parameters. Set :recur_amount to either an Integer
+      # value in cents or a Money object to have the recurring amount differ from the immediate amount.  Note 
+      # this only works if start_now is set to false.  Otherwise it is ignored.
+      def recurring_purchase(money, creditcard, interval, frequency, limit, starts_on, start_now, options = {})
+        requires!(options, :order_id)
+        params = debit_params(money, creditcard, options)
+        recur_params = {
+          :recur_unit => interval,
+          :start_now => start_now,
+          :start_date => starts_on,
+          :num_recurs => limit,
+          :period => frequency,
+          :recur_amount => amount(options[:recurring_money] || money)
+        }
+        commit('us_purchase', params, recur_params)
+      end
+
+    private # :nodoc: all
+
+      def expdate(creditcard)
+        sprintf("%.4i", creditcard.year)[-2..-1] + sprintf("%.2i", creditcard.month)
+      end
+
+      def debit_commit(commit_type, money, creditcard, options)
+        requires!(options, :order_id)
+        commit(commit_type, debit_params(money, creditcard, options))
+      end
+
+      # Common params used amongst the +purchase+ and +authorization+ methods
+      def debit_params(money, creditcard, options = {})
+        {
+          :order_id   => options[:order_id],
+          :cust_id    => options[:customer],
+          :amount     => amount(money),
+          :pan        => creditcard.number,
+          :expdate    => expdate(creditcard),
+          :crypt_type => options[:crypt_type] || @options[:crypt_type]
+        }
+      end
+
+      # Common params used amongst the +credit+, +void+ and +capture+ methods
+      def crediting_params(authorization, options = {})
+        {
+          :txn_number => split_authorization(authorization).first, 
+          :order_id   => split_authorization(authorization).last, 
+          :crypt_type => options[:crypt_type] || @options[:crypt_type]
+        }.merge(options)
+      end
+
+      # Splits an +authorization+ param and retrives the order id and 
+      # transaction number in that order.
+      def split_authorization(authorization)
+        if authorization.nil? || authorization.empty? || authorization !~ /;/
+          raise ArgumentError, 'You must include a valid authorization code (e.g. "1234;567")' 
+        else
+          authorization.split(';')
+        end
+      end
+
+      def commit(action, parameters = {}, recurring_parameters = nil)
+        response = parse(ssl_post(test? ? TEST_URL : LIVE_URL, post_data(action, parameters, recurring_parameters)))
+
+        Response.new(successful?(response), message_from(response[:message]), response,
+          :test          => test?,
+          :authorization => authorization_from(response)
+        )
+      end
+
+      # Generates a Moneris authorization string of the form 'trans_id;receipt_id'.
+      def authorization_from(response = {})
+        if response[:trans_id] && response[:receipt_id]
+          "#{response[:trans_id]};#{response[:receipt_id]}"
+        end
+      end
+
+      # Tests for a successful response from Moneris' servers
+      def successful?(response)
+        successful_action?(response) || successful_recurring?(response)
+      end
+
+      def successful_action?(response)
+        response[:response_code] && 
+        response[:complete] && 
+        (0..49).include?(response[:response_code].to_i)
+      end
+      
+      def successful_recurring?(response)
+        response[:recur_success]
+      end
+
+      def parse(xml)
+        response = { :message => "Global Error Receipt", :complete => false }
+        hashify_xml!(xml, response)
+        response
+      end
+
+      def hashify_xml!(xml, response)
+        xml = REXML::Document.new(xml)
+        return if xml.root.nil?
+        xml.elements.each('//receipt/*') do |node|
+          response[node.name.underscore.to_sym] = normalize(node.text)
+        end
+      end
+
+      def post_data(action, parameters = {}, recurring_parameters = nil)
+        xml   = REXML::Document.new
+        root  = xml.add_element("request")
+        root.add_element("store_id").text  = options[:login]
+        root.add_element("api_token").text = options[:password]
+        transaction = root.add_element(action)
+
+        # Must add the elements in the correct order
+        actions[action].each do |key|
+          transaction.add_element(key.to_s).text = parameters[key] unless parameters[key].blank?
+        end
+
+        if recurring_parameters
+          recur = transaction.add_element('recur')
+          actions['recur'].each do |key|
+            recur.add_element(key.to_s).text = recurring_parameters[key] unless recurring_parameters[key].blank?
+          end
+        end
+
+        xml.to_s
+      end
+
+      def message_from(message)
+        return 'Unspecified error' if message.blank?
+        message.gsub(/[^\w]/, ' ').split.join(" ").capitalize
+      end
+
+      # Make a Ruby type out of the response string
+      def normalize(field)
+        case field
+          when "true"     then true
+          when "false"    then false
+          when '', "null" then nil
+          else field
+        end        
+      end
+
+      def actions
+        {
+          "us_purchase"        => [:order_id, :cust_id, :amount, :pan, :expdate, :crypt_type],
+          "us_preauth"         => [:order_id, :cust_id, :amount, :pan, :expdate, :crypt_type],
+          "command"            => [:order_id],
+          "us_refund"          => [:order_id, :amount, :txn_number, :crypt_type],
+          "indrefund"          => [:order_id, :cust_id, :amount, :pan, :expdate, :crypt_type],
+          "us_completion"      => [:order_id, :comp_amount, :txn_number, :crypt_type],
+          "us_purchasecorrection" => [:order_id, :txn_number, :crypt_type],
+          "us_cavv_purchase"   => [:order_id, :cust_id, :amount, :pan, :expdate, :cav],
+          "us_cavv_preauth"    => [:order_id, :cust_id, :amount, :pan, :expdate, :cavv],
+          "us_batchcloseall"   => [],
+          "us_opentotals"      => [:ecr_number],
+          "us_batchclose"      => [:ecr_number],
+          "recur"              => [:recur_unit, :start_now, :start_date, :num_recurs, :period, :recur_amount]
+        }
+      end
+    end
+  end
+end