exact4r 0.5

data/lib/ews/transaction/mapping.rb

@@ -0,0 +1,170 @@
+require 'builder'
+
+module EWS # :nodoc:
+  module Transaction # :nodoc:
+
+    # This class handles encoding of transaction requests to the various transport formats,
+    # and the decoding of responses to transaction response objects.
+    #
+    # The supported formats are:
+    #   * REST/JSON
+    #   * REST/XML
+    #   * SOAP/XML
+    class Mapping # :nodoc:
+
+      XML_REQUEST_TAGS_TO_ATTRS = {
+        :ExactID => :gateway_id,
+        :Password => :password,
+        :Transaction_Type => :transaction_type,
+        :DollarAmount => :amount,
+        :SurchargeAmount => :surcharge_amount,
+        :Card_Number => :cc_number,
+        :Transaction_Tag => :transaction_tag,
+        :Track1 => :track1,
+        :Track2 => :track2,
+        :PAN => :pan,
+        :Authorization_Num => :auth_number,
+        :Expiry_Date => :cc_expiry,
+        :CardHoldersName => :cardholder_name,
+        :VerificationStr1 => :cc_verification_str1,
+        :VerificationStr2 => :cc_verification_str2,
+        :CVD_Presence_Ind => :cvd_presence_ind,
+        :Tax1Amount => :tax1_amount,
+        :Tax1Number => :tax1_number,
+        :Tax2Amount => :tax2_amount,
+        :Tax2Number => :tax2_number,
+        :Secure_AuthRequired => :secure_auth_required,
+        :Secure_AuthResult => :secure_auth_result,
+        :Ecommerce_Flag => :ecommerce_flag,
+        :XID => :xid,
+        :CAVV => :cavv,
+        :CAVV_Algorithm => :cavv_algorithm,
+        :Reference_No => :reference_no,
+        :Customer_Ref => :customer_ref,
+        :Reference_3 => :reference_3,
+        :Language => :language,
+        :Client_IP => :client_ip,
+        :Client_Email => :client_email,
+        :User_Name => :user_name 
+      } unless defined?(XML_REQUEST_TAGS_TO_ATTRS)
+
+      XML_RESPONSE_TAGS_TO_ATTRS = {
+        :LogonMessage => :logon_message,
+        :Error_Number =>  :error_number,
+        :Error_Description => :error_description,
+        :Transaction_Error => :transaction_error,
+        :Transaction_Approved => :transaction_approved,
+        :EXact_Resp_Code => :exact_resp_code,
+        :EXact_Message => :exact_message,
+        :Bank_Resp_Code => :bank_resp_code,
+        :Bank_Message => :bank_message,
+        :Bank_Resp_Code_2 => :bank_resp_code_2,
+        :SequenceNo => :sequence_no,
+        :AVS => :avs,
+        :CVV2 => :cvv2,
+        :Retrieval_Ref_No => :retrieval_ref_no,
+        :CAVV_Response => :cavv_response,
+        :MerchantName => :merchant_name,
+        :MerchantAddress => :merchant_address,
+        :MerchantCity => :merchant_city,
+        :MerchantProvince => :merchant_province,
+        :MerchantCountry => :merchant_country,
+        :MerchantPostal => :merchant_postal,
+        :MerchantURL => :merchant_url,
+        :CTR => :CTR
+      }.merge(XML_REQUEST_TAGS_TO_ATTRS) unless defined?(XML_RESPONSE_TAGS_TO_ATTRS)
+
+      def self.request_to_json(request)
+        request.to_json
+      end
+      def self.request_to_rest(request)
+        xml = Builder::XmlMarkup.new
+
+        xml.instruct!
+        xml.tag! 'Transaction' do
+          add_request_hash(xml, request)
+        end
+        xml.target!
+      end
+      def self.request_to_soap(request)
+        xml = Builder::XmlMarkup.new(:indent => 2)
+
+        xml.instruct!
+        xml.tag! 'soap:Envelope', REQUEST_ENVELOPE_NAMESPACES do
+          xml.tag! 'soap:Body' do
+            xml.tag! 'n1:SendAndCommit', REQUEST_SAC_ATTRIBUTES do
+              xml.tag! 'SendAndCommitSource', REQUEST_SAC_SOURCE_ATTRIBUTES do
+                add_request_hash(xml, request)
+              end
+            end
+          end
+        end
+        xml.target!
+      end
+    
+      def self.json_to_response(content)
+        response = EWS::Transaction::Response.new
+        ActiveSupport::JSON.decode(content).each { |k,v| response.send "#{k}=", v if response.respond_to?(k) }
+        response
+      end
+      def self.rest_to_response(content)
+        response = EWS::Transaction::Response.new
+        response_xml_string_to_hash(response, content)
+        response
+      end
+      def self.soap_to_response(content)
+        response = EWS::Transaction::Response.new
+        response_xml_string_to_hash(response, content, xpath = "//types:TransactionResult")
+        response
+      end
+    
+      private
+
+      # Adds the request's attributes to the XmlMarkup.
+      def self.add_request_hash(xml, request)
+        XML_REQUEST_TAGS_TO_ATTRS.each do |k, v|
+          xml.tag! k.to_s, request.send(v.to_s)
+        end
+      end
+      
+      # parses xml response string into the response attributes. The XPath identifies the root element
+      # of the payload. For REST (default) this is "//TransactionResult", for SOAP this is name space
+      # prefixed "//types:TransactionResult".
+      def self.response_xml_string_to_hash(response, xml_string, xpath = "//TransactionResult")
+        xml = REXML::Document.new(xml_string)
+        if root = REXML::XPath.first(xml, xpath)
+          root.elements.to_a.each do |node|
+            gwlib_prop_name = XML_RESPONSE_TAGS_TO_ATTRS[node.name.to_sym]
+            logger.warn("No mapping for the tag #{node.name}.") if gwlib_prop_name.nil?
+            value = (ATTR_FORMATS.include?(gwlib_prop_name)) ? node.text.send("to_#{ATTR_FORMATS[gwlib_prop_name]}") : node.text
+            response.send "#{gwlib_prop_name}=", value
+          end
+        end
+      end
+    
+      # type-conversion from strings for certain attributes
+      ATTR_FORMATS = {
+        :transaction_tag => "i",
+        :transaction_approved => "i",
+        :amount => "f",
+        :surcharge_amount => "f",
+        :tax1_amount => "f",
+        :tax2_amount => "f"
+      }
+    
+      REQUEST_ENVELOPE_NAMESPACES = {
+        "xmlns:xsd" => "http://www.w3.org/2001/XMLSchema",
+        "xmlns:env" => "http://schemas.xmlsoap.org/soap/envelope/",
+        "xmlns:xsi" => "http://www.w3.org/2001/XMLSchema-instance"
+      }
+      REQUEST_SAC_ATTRIBUTES = {
+        "xmlns:n1" => "http://secure2.e-xact.com/vplug-in/transaction/rpc-enc/Request",
+        "env:encodingStyle" => "http://schemas.xmlsoap.org/soap/encoding/"
+      }
+      REQUEST_SAC_SOURCE_ATTRIBUTES = {
+        "xmlns:n2" => "http://secure2.e-xact.com/vplug-in/transaction/rpc-enc/encodedTypes",
+        "xsi:type" => "n2:Transaction"
+      }
+    end
+  end
+end

data/lib/ews/transaction/request.rb

@@ -0,0 +1,158 @@
+module EWS # :nodoc:
+  module Transaction # :nodoc:
+    
+    # The Request class allows you to build transaction requests for
+    # submission to the E-xact Web Service.
+    #
+    # All requests will result in a financial transaction occurring, with the exception
+    # of the <tt>:transaction_details</tt> request, which looks up the details of a pre-existing
+    # transaction.
+    #
+    # The following fields are *mandatory* on all requests:
+    #   :gateway_id         the gateway to which this request should be sent
+    #   :password           your password for that gateway
+    #   :transaction_type   the type of transaction you want to perform
+    #
+    # Different transaction types will have their own additional requirements when it comes to 
+    # mandatory and optional fields, and it is recommended that the E-xact Web Service Programming
+    # Reference Guide, v8.5 be consulted. This document is contained in the Webservice Plugin ZIP file:
+    # http://www.e-xact.com/wp-content/uploads/2007/06/E-xact_Payment_Webservice_Plug-In.zip
+    #
+    # Please note that, if your chosen transaction requires it, credit card expiry dates *must* be entered in YYMM format.
+    #
+    # =Allowable transaction types
+    #  :purchase
+    #  :pre_auth
+    #  :pre_auth_completion
+    #  :forced_post
+    #  :refund
+    #  :pre_auth_only
+    #  :purchase_correction
+    #  :refund_correction
+    #  :void
+    #  :tagged_purchase
+    #  :tagged_pre_auth
+    #  :tagged_pre_auth_completion
+    #  :tagged_void
+    #  :tagged_refund
+    #  :tagged_online_debit_refund
+    #  :recurring_seed_pre_auth
+    #  :recurring_seed_purchase
+    #  :idebit_purchase
+    #  :idebit_refund
+    #  :secure_storage
+    #  :secure_storage_eft
+    #  :transaction_details
+    class Request
+
+      attr_accessor :errors
+      attr_accessor :gateway_id, :password, :transaction_type, :amount, :surcharge_amount, :cc_number, :transaction_tag, :track1, :track2, :pan, :auth_number, :cc_expiry, :cardholder_name
+      attr_accessor :cc_verification_str1, :cc_verification_str2, :cvd_presence_ind, :tax1_amount, :tax1_number, :tax2_amount, :tax2_number, :secure_auth_required, :secure_auth_result
+      attr_accessor :ecommerce_flag, :xid, :cavv, :cavv_algorithm, :reference_no, :customer_ref, :reference_3, :language, :client_ip, :client_email, :user_name 
+		
+      # Initialize a Request with a hash of values 
+      def initialize(hash = {})
+        hash.each {|k,v| self.send "#{k.to_s}=", v}
+        @errors = {}
+      end
+
+      # Set the <tt>transasction_type<tt> using either a symbol or the relevant code, e.g: for a purchase
+      # you can use either <tt>:purchase</tt> or <tt>'00'</tt>
+      def transaction_type=(type_sym)
+        # assume we're given a symbol, so look up the code
+        value = @@transaction_codes[type_sym]
+        # if nothing found, then maybe we were given an actual code?
+        value = type_sym if value.nil? and @@transaction_codes.values.include? type_sym
+
+        @transaction_type = value
+      end
+
+      # Indicates whether or not this transaction is a <tt>:transaction_details</tt> transaction
+      def is_find_transaction?
+        self.transaction_type == "CR"
+      end
+    
+      def valid?
+        errors[:transaction_type] = "transaction_type must be supplied" if self.transaction_type.blank?
+        errors[:transaction_type] = "invalid transaction_type supplied" unless @@transaction_codes.values.include? self.transaction_type
+      
+        # need to authenticate
+        errors[:gateway_id] = "gateway_id must be supplied" if self.gateway_id.blank?
+        errors[:password] = "password must be supplied" if self.password.blank?
+
+        # ensure we've been given valid amounts
+        errors[:amount] = "invalid amount supplied" unless valid_amount?(self.amount)
+        errors[:surcharge_amount] = "invalid surcharge_amount supplied" unless valid_amount?(self.surcharge_amount)
+        errors[:tax1_amount] = "invalid tax1_amount supplied" unless valid_amount?(self.tax1_amount)
+        errors[:tax2_amount] = "invalid tax2_amount supplied" unless valid_amount?(self.tax2_amount)
+      
+        errors[:cc_number] = "invalid cc_number supplied" unless valid_card_number?
+        errors[:cc_expiry] = "invalid cc_expiry supplied" unless valid_expiry_date?
+      
+        errors.empty?
+      end
+
+    private
+      def valid_amount?(amount)
+        return true if amount.blank?
+
+        (amount.class == Float) or (amount.class == Fixnum) or !amount.match /[^0-9.]/
+      end
+
+      def valid_card_number?
+        return true if self.cc_number.blank?
+
+        # do a mod10 check
+        weight = 1
+        card_number = self.cc_number.scan(/./).map(&:to_i)
+        result = card_number.reverse[1..-1].inject(0) do |sum, num|
+          weight = 1 + weight%2
+          digit = num * weight
+          sum += (digit / 10) + (digit % 10)
+        end
+        card_number.last == (10 - result % 10 ) % 10
+      end
+
+      def valid_expiry_date?
+        return true if self.cc_expiry.blank?
+      
+        # check format
+        return false unless self.cc_expiry.match /^\d{4}$/
+      
+        # check date is not in past
+        year, month = 2000 + self.cc_expiry[0..1].to_i, self.cc_expiry[2..3].to_i
+
+    		# CC is still considered valid during the month of expiry,
+    		# so just compare year and month, ignoring the rest.
+    		now = DateTime.now
+        return ((1..12) === month) && DateTime.new(year, month) >= DateTime.new(now.year, now.month)
+      end
+    
+      @@transaction_codes = {
+        :purchase => '00',
+        :pre_auth => '01',
+        :pre_auth_completion => '02',
+        :forced_post => '03',
+        :refund => '04',
+        :pre_auth_only => '05',
+        :purchase_correction => '11',
+        :refund_correction => '12',
+        :void => '13',
+        :tagged_purchase => '30',
+        :tagged_pre_auth => '31',
+        :tagged_pre_auth_completion => '32',
+        :tagged_void => '33',
+        :tagged_refund => '34',
+        :tagged_online_debit_refund => '35',
+        :recurring_seed_pre_auth => '40',
+        :recurring_seed_purchase => '41',
+        :idebit_purchase => '50',
+        :idebit_refund => '54',
+        :secure_storage => '60',
+        :secure_storage_eft => '61',
+        :transaction_details => 'CR'
+      }.freeze unless defined?(@@transaction_codes)
+
+    end
+  end
+end

data/lib/ews/transaction/response.rb

@@ -0,0 +1,18 @@
+module EWS # :nodoc:
+  module Transaction # :nodoc:
+
+    # This class encapsulates all the data returned from the E-xact Web Service.
+    class Response < EWS::Transaction::Request
+
+      attr_accessor :logon_message, :error_number, :error_description, :transaction_error, :transaction_approved
+      attr_accessor :exact_resp_code, :exact_message, :bank_resp_code, :bank_message, :bank_resp_code_2
+      attr_accessor :sequence_no, :avs, :cvv2, :retrieval_ref_no, :cavv_response
+      attr_accessor :merchant_name, :merchant_address, :merchant_city, :merchant_province, :merchant_country, :merchant_postal, :merchant_url, :CTR
+
+      # Indicates whether or not the transaction was approved
+      def approved?
+        self.transaction_approved == 1
+      end
+    end
+  end
+end

data/lib/ews/transaction/transporter.rb

@@ -0,0 +1,128 @@
+require 'net/https'
+
+module EWS # :nodoc:
+  module Transaction # :nodoc:
+    
+    # A Transporter is responsible for communicating with the E-xact Web Service in
+    # whichever dialect is chosen by the user. The available options are:
+    #   :json     REST with JSON payload
+    #   :rest     REST with XML payload
+    #   :soap     SOAP
+    #
+    # The Transporter will connect to the service, using SSL if required, and will
+    # encode Reqests to send to the service, and decode Responses received from the
+    # service.
+    #
+    # Once configured to connect to a particular service, it can be used repeatedly
+    # to send as many transactions as required.
+    class Transporter
+    
+      # Initialize a Transporter.
+      #
+      # You can specify the URL you would like the Transporter to connect to,
+      # although it defaults to https://api.e-xact.com, the location of our web
+      # service.
+      #
+      # You can also specify a hash of options as follows:
+      #   :server_cert      the path to the server's certificate
+      #   :issuer_cert      the path to the certificate of the issuer of the server certificate
+      #   :transport_type   the default transport_type for this transporter
+      #
+      # The default certificates are those required to connect to https://api.e-xact.com and the
+      # default <tt>transport_type</tt> is <tt>:rest</tt>. The default <tt>transport_type</tt> can be overridden on a per-transaction
+      # basis, if you choose to do so, by specifying it as a parameter to the <tt>send</tt> method.
+      def initialize(url = "https://api.e-xact.com/", options = {})
+        @url = URI.parse(url)
+        @server_cert = options[:server_cert] || "certs/exact.cer"
+        @issuer_cert = options[:issuer_cert] || "certs/equifax_ca.cer"
+        @transport_type = options[:issuer_cert] || :rest
+      end
+      
+      # Send a transaction request to the server
+      #
+      # <tt>request</tt>::  the Request object to encode for transmission to the server 
+      # <tt>transport_type</tt>::  (optional) the transport type to use for this transaction only. If it not specified, the default transport type for this Transporter will be used
+      def send(request, transport_type = nil)
+        raise "Request not supplied" if request.nil?
+        return false unless request.valid?
+      
+        transport_type ||= @transport_type
+        
+        raise "Transport type #{transport_type} is not supported" unless @@transport_types.include? transport_type
+      
+        if !request.is_find_transaction? or transport_type == :soap
+          content = post(request, transport_type)
+        else
+          content = get(request, transport_type)
+        end
+        
+        EWS::Transaction::Mapping.send "#{transport_type}_to_response", content
+      end
+    
+  private
+
+      def post(request, transport_type)
+        # build the request
+        req = Net::HTTP::Post.new(@url.path + "/transaction.#{@@transport_types[transport_type]}")
+        req.basic_auth(request.gateway_id, request.password)
+        if transport_type == :soap
+          # add the SOAPAction header
+          soapaction = (request.is_find_transaction?) ? "TransactionInfo" : "SendAndCommit"
+          req.add_field "soapaction", "http://secure2.e-xact.com/vplug-in/transaction/rpc-enc/#{soapaction}"
+        end
+        req.content_type = (transport_type == :json) ? "application/json" : "application/xml"
+        req.body = EWS::Transaction::Mapping.send "request_to_#{transport_type.to_s}", request
+      
+        response = get_connection.request(req)
+
+        case response
+        when Net::HTTPSuccess then response.body
+        else
+          response.error!
+        end
+      end
+
+      def get(request, transport_type)
+        # build the request
+        req = Net::HTTP::Get.new(@url.path + "/transaction/#{request.transaction_tag}.#{@@transport_types[transport_type]}")
+        req.basic_auth(request.gateway_id, request.password)
+        req.content_type = (transport_type == :json) ? "application/json" : "application/xml"
+      
+        response = get_connection.request(req)
+
+        case response
+        when Net::HTTPSuccess then response.body
+        else
+          response.error!
+        end
+      end
+    
+      def get_connection
+        connection = Net::HTTP.new(@url.host, @url.port)
+        if @url.scheme == 'https'
+          connection.use_ssl = true
+          connection.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          connection.ca_file = @issuer_cert
+          connection.verify_callback = method(:validate_certificate)
+        end
+        connection
+      end
+
+      def validate_certificate(is_ok, ctx)
+        # Don't check the root CA cert
+        unless (ctx.current_cert.subject.to_s == ctx.current_cert.issuer.to_s)
+          is_ok &&= File.open(@server_cert).read == ctx.current_cert.to_pem
+        end
+        is_ok
+      end
+
+      # what transport types we support, and their corresponding suffixes
+      @@transport_types = {
+        :rest => "xml",
+        :json => "json",
+        :soap => "xmlsoap"
+      }
+
+    end
+  end
+end