activemerchant 1.21.0 → 1.22.0

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

@@ -0,0 +1,259 @@
+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
+
+      SERVER_HOSTED_URL = 'https://migs.mastercard.com.au/vpcpay'
+      MERCHANT_HOSTED_URL = 'https://migs.mastercard.com.au/vpcdps'
+
+      # 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)
+
+        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 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

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

@@ -0,0 +1,100 @@
+module ActiveMerchant
+  module Billing
+    module MigsCodes
+      TXN_RESPONSE_CODES = {
+        '?' => 'Response Unknown',
+        '0' => 'Transaction Successful',
+        '1' => 'Transaction Declined - Bank Error',
+        '2' => 'Bank Declined Transaction',
+        '3' => 'Transaction Declined - No Reply from Bank',
+        '4' => 'Transaction Declined - Expired Card',
+        '5' => 'Transaction Declined - Insufficient funds',
+        '6' => 'Transaction Declined - Error Communicating with Bank',
+        '7' => 'Payment Server Processing Error - Typically caused by invalid input data such as an invalid credit card number. Processing errors can also occur',
+        '8' => 'Transaction Declined - Transaction Type Not Supported',
+        '9' => 'Bank Declined Transaction (Do not contact Bank)',
+        'A' => 'Transaction Aborted',
+        'C' => 'Transaction Cancelled',
+        'D' => 'Deferred Transaction',
+        'E' => 'Issuer Returned a Referral Response',
+        'F' => '3D Secure Authentication Failed',
+        'I' => 'Card Security Code Failed',
+        'L' => 'Shopping Transaction Locked (This indicates that there is another transaction taking place using the same shopping transaction number)',
+        'N' => 'Cardholder is not enrolled in 3D Secure (Authentication Only)',
+        'P' => 'Transaction is Pending',
+        'R' => 'Retry Limits Exceeded, Transaction Not Processed',
+        'S' => 'Duplicate OrderInfo used. (This is only relevant for Payment Servers that enforce the uniqueness of this field)',
+        'U' => 'Card Security Code Failed'
+      }
+
+      ISSUER_RESPONSE_CODES = {
+        '00' => 'Approved',
+        '01' => 'Refer to Card Issuer',
+        '02' => 'Refer to Card Issuer',
+        '03' => 'Invalid Merchant',
+        '04' => 'Pick Up Card',
+        '05' => 'Do Not Honor',
+        '07' => 'Pick Up Card',
+        '12' => 'Invalid Transaction',
+        '14' => 'Invalid Card Number (No such Number)',
+        '15' => 'No Such Issuer',
+        '33' => 'Expired Card',
+        '34' => 'Suspected Fraud',
+        '36' => 'Restricted Card',
+        '39' => 'No Credit Account',
+        '41' => 'Card Reported Lost',
+        '43' => 'Stolen Card',
+        '51' => 'Insufficient Funds',
+        '54' => 'Expired Card',
+        '57' => 'Transaction Not Permitted',
+        '59' => 'Suspected Fraud',
+        '62' => 'Restricted Card',
+        '65' => 'Exceeds withdrawal frequency limit',
+        '91' => 'Cannot Contact Issuer'
+      }
+
+      VERIFIED_3D_CODES = {
+        'Y' => 'The cardholder was successfully authenticated.',
+        'E' => 'The cardholder is not enrolled.',
+        'N' => 'The cardholder was not verified.',
+        'U' => 'The cardholder\'s Issuer was unable to authenticate due to a system error at the Issuer.',
+        'F' => 'An error exists in the format of the request from the merchant. For example, the request did not contain all required fields, or the format of some fields was invalid.',
+        'A' => 'Authentication of your Merchant ID and Password to the Directory Server Failed (see "What does a Payment Authentication Status of "A" mean?" on page 85).',
+        'D' => 'Error communicating with the Directory Server, for example, the Payment Server could not connect to the directory server or there was a versioning mismatch.',
+        'C' => 'The card type is not supported for authentication.',
+        'M' => 'This indicates that attempts processing was used. Verification is marked with status M - ACS attempts processing used. Payment is performed with authentication. Attempts is when a cardholder has successfully passed the directory server but decides not to continue with the authentication process and cancels.',
+        'S' => 'The signature on the response received from the Issuer could not be validated. This should be considered a failure.',
+        'T' => 'ACS timed out. The Issuer\'s ACS did not respond to the Authentication request within the time out period.',
+        'P' => 'Error parsing input from Issuer.',
+        'I' => 'Internal Payment Server system error. This could be caused by a temporary DB failure or an error in the security module or by some error in an internal system.'
+      }
+
+      class CreditCardType
+        attr_accessor :am_code, :migs_code, :migs_long_code, :name
+        def initialize(am_code, migs_code, migs_long_code, name)
+          @am_code        = am_code
+          @migs_code      = migs_code
+          @migs_long_code = migs_long_code
+          @name           = name
+        end
+      end
+
+      CARD_TYPES = [
+        # The following are 4 different representations of credit card types
+        # am_code: The active merchant code
+        # migs_code: Used in response for purchase/authorize/status
+        # migs_long_code: Used to pre-select card for server_purchase_url
+        # name: The nice display name
+        %w(american_express AE Amex             American\ Express),
+        %w(diners_club      DC Dinersclub       Diners\ Club),
+        %w(jcb              JC JCB              JCB\ Card),
+        %w(maestro          MS Maestro          Maestro\ Card),
+        %w(master           MC Mastercard       MasterCard),
+        %w(na               PL PrivateLabelCard Private\ Label\ Card),
+        %w(visa             VC Visa             Visa\ Card')
+      ].map do |am_code, migs_code, migs_long_code, name|
+        CreditCardType.new(am_code, migs_code, migs_long_code, name)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,211 @@
+require 'rexml/document'
+
+module ActiveMerchant #:nodoc:
+  module Billing #:nodoc:
+
+    # To learn more about the Moneris (US) gateway, please contact 
+    # ussales@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 MonerisUsGateway < 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, :diners_club, :discover]
+      self.homepage_url = 'http://www.monerisusa.com/'
+      self.display_name = 'Moneris (US)'
+  
+      # 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 = {})
+        deprecated CREDIT_DEPRECATION_MESSAGE
+        refund(money, authorization, options)
+      end
+   
+      def refund(money, authorization, options = {})
+        commit 'us_refund', crediting_params(authorization, :amount => amount(money))
+      end
+
+      def test?
+        @options[:test] || super
+      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 = {})
+        response = parse(ssl_post(test? ? TEST_URL : LIVE_URL, post_data(action, 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)
+        response[:response_code] && 
+        response[:complete] && 
+        (0..49).include?(response[:response_code].to_i)
+      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 = {})
+        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
+        
+        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],
+          "us_refund"             => [:order_id, :amount, :txn_number, :crypt_type],
+          "us_ind_refund"         => [: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, :cavv],
+          "us_cavv_preauth"       => [:order_id, :cust_id, :amount, :pan, :expdate, :cavv],
+          "us_batchcloseall"      => [],
+          "us_opentotals"         => [:ecr_number],
+          "us_batchclose"         => [:ecr_number]
+        }
+      end
+    end
+  end
+end