activemerchant-nsp 1.27.0

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

@@ -0,0 +1,323 @@
+module ActiveMerchant #:nodoc:
+  module Billing #:nodoc:
+    # For more information on the Metrics Global Payment Gateway, visit the {Metrics Global website}[www.metricsglobal.com].
+    # Further documentation on AVS and CVV response codes are available under the support section of the Metrics Global
+    # control panel.
+    #
+    # === Metrics Global Payment Gateway Authentication
+    #
+    # The login and password for the gateway are the same as the username and password used to log in to the Metrics Global
+    # control panel. Contact Metrics Global support to receive credentials for the control panel.
+    #
+    # === Demo Account
+    #
+    # There is a public demo account available with the following credentials:
+    #
+    # Login: demo
+    # Password: password
+    class MetricsGlobalGateway < Gateway
+      API_VERSION = '3.1'
+
+      class_attribute :test_url, :live_url
+
+      self.test_url = "https://secure.metricsglobalgateway.com/gateway/transact.dll?testing=true"
+      self.live_url = "https://secure.metricsglobalgateway.com/gateway/transact.dll"
+
+      class_attribute :duplicate_window
+
+      APPROVED, DECLINED, ERROR, FRAUD_REVIEW = 1, 2, 3, 4
+
+      RESPONSE_CODE, RESPONSE_REASON_CODE, RESPONSE_REASON_TEXT = 0, 2, 3
+      AVS_RESULT_CODE, TRANSACTION_ID, CARD_CODE_RESPONSE_CODE  = 5, 6, 38
+
+      self.supported_countries = ['US']
+      self.supported_cardtypes = [:visa, :master, :american_express, :discover, :diners_club, :jcb]
+      self.homepage_url = 'http://www.metricsglobal.com'
+      self.display_name = 'Metrics Global'
+
+      CARD_CODE_ERRORS = %w( N S )
+      AVS_ERRORS = %w( A E N R W Z )
+      AVS_REASON_CODES = %w(27 45)
+
+      # Creates a new MetricsGlobalGateway
+      #
+      # The gateway requires that a valid login and password be passed
+      # in the +options+ hash.
+      #
+      # ==== Options
+      #
+      # * <tt>:login</tt> -- The username required to access the Metrics Global control panel. (REQUIRED)
+      # * <tt>:password</tt> -- The password required to access the Metrics Global control panel. (REQUIRED)
+      # * <tt>:test</tt> -- +true+ or +false+. If true, perform transactions against the test server. 
+      #   Otherwise, perform transactions against the production server.
+      def initialize(options = {})
+        requires!(options, :login, :password)
+        @options = options
+        super
+      end
+
+      # Performs an authorization, which reserves the funds on the customer's credit card, but does not
+      # charge the card.
+      #
+      # ==== Parameters
+      #
+      # * <tt>money</tt> -- The amount to be authorized as an Integer value in cents.
+      # * <tt>creditcard</tt> -- The CreditCard details for the transaction.
+      # * <tt>options</tt> -- A hash of optional parameters.
+      def authorize(money, creditcard, options = {})
+        post = {}
+        add_invoice(post, options)
+        add_creditcard(post, creditcard)
+        add_address(post, options)
+        add_customer_data(post, options)
+        add_duplicate_window(post)
+
+        commit('AUTH_ONLY', money, post)
+      end
+
+      # Perform a purchase, which is essentially an authorization and capture in a single operation.
+      #
+      # ==== Parameters
+      #
+      # * <tt>money</tt> -- The amount to be purchased as an Integer value in cents.
+      # * <tt>creditcard</tt> -- The CreditCard details for the transaction.
+      # * <tt>options</tt> -- A hash of optional parameters.
+      def purchase(money, creditcard, options = {})
+        post = {}
+        add_invoice(post, options)
+        add_creditcard(post, creditcard)
+        add_address(post, options)
+        add_customer_data(post, options)
+        add_duplicate_window(post)
+
+        commit('AUTH_CAPTURE', money, post)
+      end
+
+      # Captures the funds from an authorized transaction.
+      #
+      # ==== Parameters
+      #
+      # * <tt>money</tt> -- The amount to be captured as an Integer value in cents.
+      # * <tt>authorization</tt> -- The authorization returned from the previous authorize request.
+      def capture(money, authorization, options = {})
+        post = {:trans_id => authorization}
+        add_customer_data(post, options)
+        commit('PRIOR_AUTH_CAPTURE', money, post)
+      end
+
+      # Void a previous transaction
+      #
+      # ==== Parameters
+      #
+      # * <tt>authorization</tt> - The authorization returned from the previous authorize request.
+      def void(authorization, options = {})
+        post = {:trans_id => authorization}
+        add_duplicate_window(post)
+        commit('VOID', nil, post)
+      end
+
+      # Refund a transaction.
+      #
+      # This transaction indicates to the gateway that
+      # money should flow from the merchant to the customer.
+      #
+      # ==== Parameters
+      #
+      # * <tt>money</tt> -- The amount to be credited to the customer as an Integer value in cents.
+      # * <tt>identification</tt> -- The ID of the original transaction against which the refund is being issued.
+      # * <tt>options</tt> -- A hash of parameters.
+      #
+      # ==== Options
+      #
+      # * <tt>:card_number</tt> -- The credit card number the refund is being issued to. (REQUIRED)
+      # * <tt>:first_name</tt> -- The first name of the account being refunded.
+      # * <tt>:last_name</tt> -- The last name of the account being refunded.
+      # * <tt>:zip</tt> -- The postal code of the account being refunded.
+      def refund(money, identification, options = {})
+        requires!(options, :card_number)
+
+        post = { :trans_id => identification,
+                 :card_num => options[:card_number]
+               }
+
+        post[:first_name] = options[:first_name] if options[:first_name]
+        post[:last_name] = options[:last_name] if options[:last_name]
+        post[:zip] = options[:zip] if options[:zip]
+
+        add_invoice(post, options)
+        add_duplicate_window(post)
+
+        commit('CREDIT', money, post)
+      end
+
+      def credit(money, identification, options = {})
+        deprecated CREDIT_DEPRECATION_MESSAGE
+        refund(money, identification, options)
+      end
+
+      private
+      
+      def commit(action, money, parameters)
+        parameters[:amount] = amount(money) unless action == 'VOID'
+
+        # Only activate the test_request when the :test option is passed in
+        parameters[:test_request] = @options[:test] ? 'TRUE' : 'FALSE'
+
+        url = test? ? self.test_url : self.live_url
+        data = ssl_post url, post_data(action, parameters)
+
+        response = parse(data)
+
+        message = message_from(response)
+
+        # Return the response. The authorization can be taken out of the transaction_id
+        # Test Mode on/off is something we have to parse from the response text.
+        # It usually looks something like this
+        #
+        #   (TESTMODE) Successful Sale
+        test_mode = test? || message =~ /TESTMODE/
+
+        Response.new(success?(response), message, response, 
+          :test => test_mode, 
+          :authorization => response[:transaction_id],
+          :fraud_review => fraud_review?(response),
+          :avs_result => { :code => response[:avs_result_code] },
+          :cvv_result => response[:card_code]
+        )
+      end
+
+      def success?(response)
+        response[:response_code] == APPROVED
+      end
+
+      def fraud_review?(response)
+        response[:response_code] == FRAUD_REVIEW
+      end
+
+      def parse(body)
+        fields = split(body)
+
+        results = {
+          :response_code => fields[RESPONSE_CODE].to_i,
+          :response_reason_code => fields[RESPONSE_REASON_CODE], 
+          :response_reason_text => fields[RESPONSE_REASON_TEXT],
+          :avs_result_code => fields[AVS_RESULT_CODE],
+          :transaction_id => fields[TRANSACTION_ID],
+          :card_code => fields[CARD_CODE_RESPONSE_CODE]
+        }
+        results
+      end
+
+      def post_data(action, parameters = {})
+        post = {}
+
+        post[:version]        = API_VERSION
+        post[:login]          = @options[:login]
+        post[:tran_key]       = @options[:password]
+        post[:relay_response] = "FALSE"
+        post[:type]           = action
+        post[:delim_data]     = "TRUE"
+        post[:delim_char]     = ","
+        post[:encap_char]     = "$"
+        post[:solution_ID]    = application_id if application_id.present? && application_id != "ActiveMerchant"
+
+        request = post.merge(parameters).collect { |key, value| "x_#{key}=#{CGI.escape(value.to_s)}" }.join("&")
+        request
+      end
+
+      def add_invoice(post, options)
+        post[:invoice_num] = options[:order_id]
+        post[:description] = options[:description]
+      end
+
+      def add_creditcard(post, creditcard)
+        post[:card_num]   = creditcard.number
+        post[:card_code]  = creditcard.verification_value if creditcard.verification_value?
+        post[:exp_date]   = expdate(creditcard)
+        post[:first_name] = creditcard.first_name
+        post[:last_name]  = creditcard.last_name
+      end
+
+      def add_customer_data(post, options)
+        if options.has_key? :email
+          post[:email] = options[:email]
+          post[:email_customer] = false
+        end
+
+        if options.has_key? :customer
+          post[:cust_id] = options[:customer]
+        end
+
+        if options.has_key? :ip
+          post[:customer_ip] = options[:ip]
+        end
+      end
+      
+      # x_duplicate_window won't be sent by default, because sending it changes the response.
+      # "If this field is present in the request with or without a value, an enhanced duplicate transaction response will be sent."
+      def add_duplicate_window(post)
+        unless duplicate_window.nil?
+          post[:duplicate_window] = duplicate_window
+        end
+      end
+
+      def add_address(post, options)
+        if address = options[:billing_address] || options[:address]
+          post[:address] = address[:address1].to_s
+          post[:company] = address[:company].to_s
+          post[:phone]   = address[:phone].to_s
+          post[:zip]     = address[:zip].to_s
+          post[:city]    = address[:city].to_s
+          post[:country] = address[:country].to_s
+          post[:state]   = address[:state].blank?  ? 'n/a' : address[:state]
+        end
+        
+        if address = options[:shipping_address]
+          post[:ship_to_first_name] = address[:first_name].to_s
+          post[:ship_to_last_name] = address[:last_name].to_s
+          post[:ship_to_address] = address[:address1].to_s
+          post[:ship_to_company] = address[:company].to_s
+          post[:ship_to_phone]   = address[:phone].to_s
+          post[:ship_to_zip]     = address[:zip].to_s
+          post[:ship_to_city]    = address[:city].to_s
+          post[:ship_to_country] = address[:country].to_s
+          post[:ship_to_state]   = address[:state].blank?  ? 'n/a' : address[:state]
+        end
+      end
+
+      # 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
+        end
+      end
+
+      def message_from(results)  
+        if results[:response_code] == DECLINED
+          return CVVResult.messages[ results[:card_code] ] if CARD_CODE_ERRORS.include?(results[:card_code])
+          if AVS_REASON_CODES.include?(results[:response_reason_code]) && AVS_ERRORS.include?(results[:avs_result_code])
+            return AVSResult.messages[ results[:avs_result_code] ] 
+          end
+        end
+
+        (results[:response_reason_text] ? results[:response_reason_text].chomp('.') : '')
+      end
+
+      def expdate(creditcard)
+        year  = sprintf("%.4i", creditcard.year)
+        month = sprintf("%.2i", creditcard.month)
+
+        "#{month}#{year[-2..-1]}"
+      end
+
+      def split(response)
+        response[1..-2].split(/\$,\$/)
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,263 @@
+require File.dirname(__FILE__) + '/migs/migs_codes'
+
+require 'digest/md5' # Used in add_secure_hash
+
+module ActiveMerchant #:nodoc:
+  module Billing #:nodoc:
+    class MigsGateway < Gateway
+      include MigsCodes
+
+      API_VERSION = 1
+
+      class_attribute :server_hosted_url, :merchant_hosted_url
+
+      self.server_hosted_url = 'https://migs.mastercard.com.au/vpcpay'
+      self.merchant_hosted_url = 'https://migs.mastercard.com.au/vpcdps'
+
+      self.live_url = self.server_hosted_url
+
+      # MiGS is supported throughout Asia Pacific, Middle East and Africa
+      # MiGS is used in Australia (AU) by ANZ (eGate), CBA (CommWeb) and more
+      # Source of Country List: http://www.scribd.com/doc/17811923
+      self.supported_countries = %w(AU AE BD BN EG HK ID IN JO KW LB LK MU MV MY NZ OM PH QA SA SG TT VN)
+
+      # The card types supported by the payment gateway
+      self.supported_cardtypes = [:visa, :master, :american_express, :diners_club, :jcb]
+
+      self.money_format = :cents
+
+      # The homepage URL of the gateway
+      self.homepage_url = 'http://mastercard.com/mastercardsps'
+
+      # The name of the gateway
+      self.display_name = 'MasterCard Internet Gateway Service (MiGS)'
+
+      # Creates a new MigsGateway
+      # The advanced_login/advanced_password fields are needed for
+      # advanced methods such as the capture, refund and status methods
+      #
+      # ==== Options
+      #
+      # * <tt>:login</tt> -- The MiGS Merchant ID (REQUIRED)
+      # * <tt>:password</tt> -- The MiGS Access Code (REQUIRED)
+      # * <tt>:secure_hash</tt> -- The MiGS Secure Hash
+      # (Required for Server Hosted payments)
+      # * <tt>:advanced_login</tt> -- The MiGS AMA User
+      # * <tt>:advanced_password</tt> -- The MiGS AMA User's password
+      def initialize(options = {})
+        requires!(options, :login, :password)
+        @test = options[:login].start_with?('TEST')
+        @options = options
+        super
+      end
+
+      # ==== Options
+      #
+      # * <tt>:order_id</tt> -- A reference for tracking the order (REQUIRED)
+      # * <tt>:unique_id</tt> -- A unique id for this request (Max 40 chars).
+      # If not supplied one will be generated.
+      def purchase(money, creditcard, options = {})
+        requires!(options, :order_id)
+
+        post = {}
+        post[:Amount] = amount(money)
+        add_invoice(post, options)
+        add_creditcard(post, creditcard)
+        add_standard_parameters('pay', post, options[:unique_id])
+
+        commit(post)
+      end
+
+      # MiGS works by merchants being either purchase only or authorize/capture
+      # So authorize is the same as purchase when in authorize mode
+      alias_method :authorize, :purchase
+
+      # ==== Options
+      #
+      # * <tt>:unique_id</tt> -- A unique id for this request (Max 40 chars).
+      # If not supplied one will be generated.
+      def capture(money, authorization, options = {})
+        requires!(@options, :advanced_login, :advanced_password)
+
+        post = options.merge(:TransNo => authorization)
+        post[:Amount] = amount(money)
+        add_advanced_user(post)
+        add_standard_parameters('capture', post, options[:unique_id])
+
+        commit(post)
+      end
+
+      # ==== Options
+      #
+      # * <tt>:unique_id</tt> -- A unique id for this request (Max 40 chars).
+      # If not supplied one will be generated.
+      def refund(money, authorization, options = {})
+        requires!(@options, :advanced_login, :advanced_password)
+
+        post = options.merge(:TransNo => authorization)
+        post[:Amount] = amount(money)
+        add_advanced_user(post)
+        add_standard_parameters('refund', post, options[:unique_id])
+
+        commit(post)
+      end
+
+      def credit(money, authorization, options = {})
+        deprecated CREDIT_DEPRECATION_MESSAGE
+        refund(money, authorization, options)
+      end
+
+      # Checks the status of a previous transaction
+      # This can be useful when a response is not received due to network issues
+      #
+      # ==== Parameters
+      #
+      # * <tt>unique_id</tt> -- Unique id of transaction to find.
+      #   This is the value of the option supplied in other methods or
+      #   if not supplied is returned with key :MerchTxnRef
+      def status(unique_id)
+        requires!(@options, :advanced_login, :advanced_password)
+
+        post = {}
+        add_advanced_user(post)
+        add_standard_parameters('queryDR', post, unique_id)
+
+        commit(post)
+      end
+
+      # Generates a URL to redirect user to MiGS to process payment
+      # Once user is finished MiGS will redirect back to specified URL
+      # With a response hash which can be turned into a Response object
+      # with purchase_offsite_response
+      #
+      # ==== Options
+      #
+      # * <tt>:order_id</tt> -- A reference for tracking the order (REQUIRED)
+      # * <tt>:locale</tt> -- Change the language of the redirected page
+      #   Values are 2 digit locale, e.g. en, es
+      # * <tt>:return_url</tt> -- the URL to return to once the payment is complete
+      # * <tt>:card_type</tt> -- Providing this skips the card type step.
+      #   Values are ActiveMerchant formats: e.g. master, visa, american_express, diners_club
+      # * <tt>:unique_id</tt> -- Unique id of transaction to find.
+      #   If not supplied one will be generated.
+      def purchase_offsite_url(money, options = {})
+        requires!(options, :order_id, :return_url)
+        requires!(@options, :secure_hash)
+
+        post = {}
+        post[:Amount] = amount(money)
+        add_invoice(post, options)
+        add_creditcard_type(post, options[:card_type]) if options[:card_type]
+
+        post.merge!(
+          :Locale => options[:locale] || 'en',
+          :ReturnURL => options[:return_url]
+        )
+
+        add_standard_parameters('pay', post, options[:unique_id])
+
+        add_secure_hash(post)
+
+        self.server_hosted_url + '?' + post_data(post)
+      end
+
+      # Parses a response from purchase_offsite_url once user is redirected back
+      #
+      # ==== Parameters
+      #
+      # * <tt>data</tt> -- All params when offsite payment returns
+      # e.g. returns to http://company.com/return?a=1&b=2, then input "a=1&b=2"
+      def purchase_offsite_response(data)
+        requires!(@options, :secure_hash)
+
+        response_hash = parse(data)
+
+        expected_secure_hash = calculate_secure_hash(response_hash.reject{|k, v| k == :SecureHash}, @options[:secure_hash])
+        unless response_hash[:SecureHash] == expected_secure_hash
+          raise SecurityError, "Secure Hash mismatch, response may be tampered with"
+        end
+
+        response_object(response_hash)
+      end
+
+      private
+
+      def add_advanced_user(post)
+        post[:User] = @options[:advanced_login]
+        post[:Password] = @options[:advanced_password]
+      end
+
+      def add_invoice(post, options)
+        post[:OrderInfo] = options[:order_id]
+      end
+
+      def add_creditcard(post, creditcard)
+        post[:CardNum] = creditcard.number
+        post[:CardSecurityCode] = creditcard.verification_value if creditcard.verification_value?
+        post[:CardExp] = format(creditcard.year, :two_digits) + format(creditcard.month, :two_digits)
+      end
+
+      def add_creditcard_type(post, card_type)
+        post[:Gateway]  = 'ssl'
+        post[:card] = CARD_TYPES.detect{|ct| ct.am_code == card_type}.migs_long_code
+      end
+
+      def parse(body)
+        params = CGI::parse(body)
+        hash = {}
+        params.each do |key, value|
+          hash[key.gsub('vpc_', '').to_sym] = value[0]
+        end
+        hash
+      end
+
+      def commit(post)
+        data = ssl_post self.merchant_hosted_url, post_data(post)
+        response_hash = parse(data)
+        response_object(response_hash)
+      end
+
+      def response_object(response)
+        Response.new(success?(response), response[:Message], response,
+          :test => @test,
+          :authorization => response[:TransactionNo],
+          :fraud_review => fraud_review?(response),
+          :avs_result => { :code => response[:AVSResultCode] },
+          :cvv_result => response[:CSCResultCode]
+        )
+      end
+
+      def success?(response)
+        response[:TxnResponseCode] == '0'
+      end
+
+      def fraud_review?(response)
+        ISSUER_RESPONSE_CODES[response[:AcqResponseCode]] == 'Suspected Fraud'
+      end
+
+      def add_standard_parameters(action, post, unique_id = nil)
+        post.merge!(
+          :Version     => API_VERSION,
+          :Merchant    => @options[:login],
+          :AccessCode  => @options[:password],
+          :Command     => action,
+          :MerchTxnRef => unique_id || generate_unique_id.slice(0, 40)
+        )
+      end
+
+      def post_data(post)
+        post.collect { |key, value| "vpc_#{key}=#{CGI.escape(value.to_s)}" }.join("&")
+      end
+
+      def add_secure_hash(post)
+        post[:SecureHash] = calculate_secure_hash(post, @options[:secure_hash])
+      end
+
+      def calculate_secure_hash(post, secure_hash)
+        sorted_values = post.sort_by(&:to_s).map(&:last)
+        input = secure_hash + sorted_values.join
+        Digest::MD5.hexdigest(input).upcase
+      end
+    end
+  end
+end