activemerchant 1.1.0 → 1.2.0

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

@@ -3,10 +3,21 @@ 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
       attr_reader :url 
       attr_reader :response
       attr_reader :options
+      
+      self.supported_countries = ['CA']
+      self.supported_cardtypes = [:visa, :master]
+      self.homepage_url = 'http://www.moneris.com/'
+      self.display_name = 'Moneris'
 
       TEST_URL = 'https://esqa.moneris.com/gateway2/servlet/MpgRequest'
       LIVE_URL = 'https://www3.moneris.com/gateway2/servlet/MpgRequest'
@@ -15,145 +26,167 @@ module ActiveMerchant #:nodoc:
       # password is your API Token
       def initialize(options = {})
         requires!(options, :login, :password)
-      
-        @options = {
-          :strict_ssl => true,
-          :crypt_type => 7
-        }.update(options)
-      
+        @options = { :crypt_type => 7 }.update(options)
         @url = test? ? TEST_URL : LIVE_URL      
-        
         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 = {})
-        requires!(options, :order_id)
-
-        parameters = {
-          :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]
-        }                                                             
-      
-        commit('preauth', parameters)      
+        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 = {})
-        requires!(options, :order_id)
-      
-        parameters = {
-          :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]
-        }                                                             
-      
-        commit('purchase', parameters)      
+        debit_commit 'purchase', money, creditcard, options
       end
      
-      # Moneris requires both the order_id and the transaction number of
+      # 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 = {})
-        txn_number, order_id = authorization.split(';')
-
-          parameters = {
-            :txn_number => txn_number,
-            :order_id => order_id,
-            :comp_amount => amount(money),
-            :crypt_type => options[:crypt_type] || @options[:crypt_type]
-          }
-
-        commit('completion', parameters)      
+        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 = {})
-        txn_number, order_id = authorization.split(';')
-
-          parameters = {
-            :txn_number => txn_number,
-            :order_id => order_id,
-            :crypt_type => options[:crypt_type] || @options[:crypt_type]
-          }
-
-        commit('purchasecorrection', parameters)      
+        commit 'purchasecorrection', crediting_params(authorization)
       end
-    
-      # We support visa and master card
-      def self.supported_cardtypes
-        [:visa, :master]
+      
+      # 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                       
+   
+    private # :nodoc: all
     
       def expdate(creditcard)
-        year  = sprintf("%.4i", creditcard.year)
-        month = sprintf("%.2i", creditcard.month)
-
-        "#{year[-2..-1]}#{month}"
+        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)                                 
+      def commit(action, parameters = {})
+        # TODO This part still needs to be refactored
         if result = test_result_from_cc_number(parameters[:pan])
           return result
         end
         
-        data = ssl_post @url, post_data(action, parameters)
-        @response = parse(data)
+        @response = parse(ssl_post(@url, post_data(action, parameters)))
 
-        success = (response[:response_code] and response[:complete] and (0..49).include?(response[:response_code].to_i) )
-        message = message_form(response[:message])
-        authorization = "#{response[:trans_id]};#{response[:receipt_id]}" if response[:trans_id] && response[:receipt_id]
-        
-        Response.new(success, message, @response,
-          :test => test?,
-          :authorization => authorization
+        Response.new(successful_response?(response), message_form(response[:message]), @response,
+          :test          => test?,
+          :authorization => authorization_string(response)
         )
       end
+      
+      # Generates a Moneris authorization string of the form 'trans_id;receipt_id'.
+      def authorization_string(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?(response = {})
+        response[:response_code] && 
+        response[:complete] && 
+        (0..49).include?(response[:response_code].to_i)
+      end
                                                
-      # Parse moneris response xml into a convinient hash
+      # Parse Moneris' response XML into a convinient Hash.
+      # 
+      # Expected XML format:
+      # 
+      #   "<?xml version=\"1.0\"?><response><receipt>".
+      #   "<ReceiptId>Global Error Receipt</ReceiptId>".
+      #   "<ReferenceNum>null</ReferenceNum>
+      #   <ResponseCode>null</ResponseCode>".
+      #   "<ISO>null</ISO> 
+      #   <AuthCode>null</AuthCode>
+      #   <TransTime>null</TransTime>".
+      #   "<TransDate>null</TransDate>
+      #   <TransType>null</TransType>
+      #   <Complete>false</Complete>".
+      #   "<Message>null</Message>
+      #   <TransAmount>null</TransAmount>".
+      #   "<CardType>null</CardType>".
+      #   "<TransID>null</TransID>
+      #   <TimedOut>null</TimedOut>".
+      #   "</receipt></response>
       def parse(xml)
-        #  "<?xml version=\"1.0\"?><response><receipt>".
-        #  "<ReceiptId>Global Error Receipt</ReceiptId>".
-        #  "<ReferenceNum>null</ReferenceNum>
-        #  <ResponseCode>null</ResponseCode>".
-        #  "<ISO>null</ISO> 
-        #  <AuthCode>null</AuthCode>
-        #  <TransTime>null</TransTime>".
-        #  "<TransDate>null</TransDate>
-        #  <TransType>null</TransType>
-        #  <Complete>false</Complete>".
-        #  "<Message>null</Message>
-        #  <TransAmount>null</TransAmount>".
-        #  "<CardType>null</CardType>".
-        #  "<TransID>null</TransID>
-        #  <TimedOut>null</TimedOut>".
-        #  "</receipt></response>      
-
-        response = {:message => "Global Error Receipt", :complete => false}
-
-        xml = REXML::Document.new(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 unless xml.root.nil?
-
-        response
-      end     
+        end
+      end
 
       def post_data(action, parameters = {})
         xml   = REXML::Document.new
         root  = xml.add_element("request")
-        root.add_element("store_id").text = options[:login]
+        root.add_element("store_id").text  = options[:login]
         root.add_element("api_token").text = options[:password]
         transaction = root.add_element(action)
 
@@ -170,36 +203,33 @@ module ActiveMerchant #:nodoc:
         message.gsub(/[^\w]/, ' ').split.join(" ").capitalize
       end
 
-      # Make a ruby type out of the response string
+      # Make a Ruby type out of the response string
       def normalize(field)
         case field
-        when "true"   then true
-        when "false"  then false
-        when ""       then nil
-        when "null"   then nil
-        else field
+          when "true"     then true
+          when "false"    then false
+          when '', "null" then nil
+          else field
         end        
-      end         
-    
+      end
+      
       def actions
-        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]
+        }
       end
-
-      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],
-      }    
     end
   end
 end

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

@@ -0,0 +1,257 @@
+#
+# Gateway for netregistry.com.au.
+#
+# Note that NetRegistry itself uses gateway service providers.  At the
+# time of this writing, there are at least two (Quest and Ingenico).
+# This module has only been tested with Quest.
+#
+# Also note that NetRegistry does not offer a test mode, nor does it
+# have support for the authorize/capture/void functionality by default
+# (you may arrange for this as described in "Programming for
+# NetRegistry's E-commerce Gateway." [http://rubyurl.com/hNG]), and no
+# #void functionality is documented.  As a result, the #authorize and
+# #capture have not yet been tested through a live gateway, and #void
+# will raise an error.
+#
+# If you have this functionality enabled, please consider contributing
+# to ActiveMerchant by writing tests/code for these methods, and
+# submitting a patch.
+#
+# In addition to the standard ActiveMerchant functionality, the
+# response will contain a 'receipt' parameter
+# (response.params['receipt']) if a receipt was issued by the gateway.
+# Also, a logger may be provided when instantiating the gateway to log
+# all data sent to/from the gateway (with sensitive information
+# hidden).
+#
+module ActiveMerchant
+  module Billing
+    class NetRegistryGateway < Gateway
+      LIVE_URL = 'https://4tknox.au.com/cgi-bin/themerchant.au.com/ecom/external2.pl'
+      
+      self.supported_countries = ['AU']
+      
+      # Note that support for Diners, Amex, and JCB require extra
+      # steps in setting up your account, as detailed in
+      # "Programming for NetRegistry's E-commerce Gateway."
+      # [http://rubyurl.com/hNG]
+      self.supported_cardtypes = [:visa, :master, :diners_club, :american_express, :jcb]
+      self.display_name = 'NetRegistry'
+      self.homepage_url = 'http://www.netregistry.com.au'
+      
+      # Create a new NetRegistry gateway.
+      #
+      # Options :login and :password must be given.
+      #
+      def initialize(options = {})
+        requires!(options, :login, :password)
+        @logger = options[:logger]
+        @options = options
+        super
+      end
+
+      #
+      # A Logger object used to write extra debugging output to.  nil
+      # for none.
+      #
+      attr_accessor :logger
+
+      #
+      # Note that #authorize and #capture only work if your account
+      # vendor is St George, and if your account has been setup as
+      # described in "Programming for NetRegistry's E-commerce
+      # Gateway." [http://rubyurl.com/hNG]
+      #
+      def authorize(money, credit_card, options = {})
+        post(options[:description],
+             'COMMAND' => 'preauth',
+             'AMOUNT'  => amount(money),
+             'CCNUM'   => credit_card.number,
+             'CCEXP'   => expiry(credit_card))
+      end
+
+      #
+      # Note that #authorize and #capture only work if your account
+      # vendor is St George, and if your account has been setup as
+      # described in "Programming for NetRegistry's E-commerce
+      # Gateway." [http://rubyurl.com/hNG]
+      #
+      def capture(money, authorization, options = {})
+        credit_card = options[:credit_card]
+        post(options[:description],
+             'COMMAND'    => 'completion',
+             'PREAUTHNUM' => authorization,
+             'AMOUNT'     => amount(money),
+             'CCNUM'      => credit_card.number,
+             'CCEXP'      => expiry(credit_card))
+      end
+
+      def purchase(money, credit_card, options = {})
+        post(options[:description],
+             'COMMAND' => 'purchase',
+             'AMOUNT'  => amount(money),
+             'CCNUM'   => credit_card.number,
+             'CCEXP'   => expiry(credit_card))
+      end
+
+      def credit(money, identification, options = {})
+        post(options[:description],
+             'COMMAND' => 'refund',
+             'AMOUNT'  => amount(money),
+             'TXNREF'  => identification)
+      end
+      
+      # Specific to NetRegistry.
+      #
+      # Run a 'status' command.  This lets you view the status of a
+      # completed transaction.
+      #
+      def status(identification)
+        post(options[:description],
+             'COMMAND' => 'status',
+             'TXNREF'  => identification)
+      end
+
+      private  # -----------------------------------------------------
+
+      #
+      # Return the expiry for the given creditcard in the required
+      # format for a command.
+      #
+      def expiry(credit_card)
+        month = format(credit_card.month, :two_digits)
+        year  = format(credit_card.year , :two_digits)
+        "#{month}/#{year}"
+      end
+
+      #
+      # Post the a request with the given parameters and return the
+      # response object.
+      #
+      # Login and password are added automatically, and the comment is
+      # omitted if nil.
+      #
+      def post(comment, keyvals)
+        if result = test_result_from_cc_number(keyvals['CCNUM'])
+          return result
+        end
+        
+        log "Executing #{keyvals['COMMAND']}:"
+        login    = @options[:login]
+        password = @options[:password]
+
+        # make query
+        keyvals['COMMENT'] = comment if comment
+        keyvals['LOGIN'] = "#{login}/#{password}"
+        str = URI.encode(keyvals.map{|k,v| "#{k}=#{v}"}.join('&'))
+        log "  ActiveMerchant/NetRegistry: sending: #{obscure_send_string(str)}"
+
+        # get gateway response
+        text = ssl_post(LIVE_URL, str)
+        log "  ActiveMerchant/NetRegistry: received:"
+        obscure_recv_string(text).each do |line|
+          log "    #{line}"
+        end
+
+        # make response object
+        response = parse_response(text, keyvals['COMMAND'])
+
+        return response
+      end
+
+      #
+      # Parse the text returned from the gateway into a Response object.
+      #
+      def parse_response(text, command)
+        params = {'original_text' => text}
+        sio = StringIO.new(text)
+        params['status'] = sio.gets.chomp
+        params['rrn'] = sio.gets.chomp
+
+        if sio.eof?
+          # some short errors have nothing else, e.g., "Invalid expiry
+          # format"
+          message = params.delete('rrn')
+          return Response.new(false, message, params)
+        end
+
+        # parse receipt
+        receipt = ''
+        while (line = sio.gets)
+          break if line.strip == '.'
+          receipt << line
+        end
+
+        # parse params
+        while (line = sio.gets)
+          line.chomp!
+          key, val = line.split(/=/, 2)
+          params[key] = val
+        end
+
+        params['receipt'] = receipt
+        authorization =
+          case command
+          when 'purchase'
+            params['txn_ref']
+          when 'preauth'
+            params['transaction_no']
+          else
+            nil
+          end
+
+        Response.new(params['status'] == 'approved',
+                     params['response_text'],
+                     params,
+                     :authorization => authorization)
+      end
+
+      #
+      # Log a message if logging is enabled.
+      #
+      def log(msg)
+        logger.info(msg.chomp) unless logger.nil?
+      end
+
+      #
+      # Return a copy of the given string (to be sent to the gateway),
+      # with sensitive information hidden.
+      #
+      def obscure_send_string(string)
+        string.gsub(/LOGIN=[^&]+/) do |keyval|
+          keyval.sub(/[^\/]+\z/){|pass| '*'*pass.size}
+        end.gsub(/CCNUM=[^&]+/) do |keyval|
+          keyval.sub(/[^=]+\z/){|num| obscure_card_number(num)}
+        end.gsub(/CCEXP=[^&]+/) do |keyval|
+          keyval.sub(/[^=]+\z/){|num| obscure_card_expiry(num)}
+        end
+      end
+
+      #
+      # Return a copy of the given string (received from the gateway),
+      # with sensitive information hidden.
+      #
+      def obscure_recv_string(string)
+        string.
+          gsub(/(card_(?:no|number)=)(.*)$/){$1 << obscure_card_number($2)}.
+          gsub(/(card_expiry=)(.*)$/){$1 << obscure_card_expiry($2)}
+      end
+
+      #
+      # Obscure a credit card number.
+      #
+      def obscure_card_number(number)
+        return number if number.size < 4
+        number[0...-4] = '*'*(number.size-4)
+        return number
+      end
+
+      #
+      # Obscure a credit card expiry.
+      #
+      def obscure_card_expiry(expiry)
+        expiry.gsub(/\d/, '*')
+      end
+    end
+  end
+end