xpay 0.0.5

data/lib/xpay/core/operation.rb

@@ -0,0 +1,58 @@
+module Xpay
+
+  # The following attribute is required for each operation:
+  # amount -> supplied either as String or Integer, must be in Base i.e.: 10.99 becomes 1099
+  #
+  # The following attributes are taken from the default config and can be overridden here for this request only:
+  # auth_type: defaults to the module default. Options are: AUTH, ST3DCARDQUERY, AUTHREVERSAL,REFUND,REFUNDREVERSAL, SETTLEMENT
+  # currency: defaults to module default. Override with approved currencies
+  # settlement day:
+  # callback_url: Specify the callback url for the callback from the 3D secure server. (Will be the bank that issued the card usually)
+  # site_reference and site_alias: are usually the same. Override the default setting for this request
+  # merchant_name: same as above
+  #
+  # The following attributes are entirely optional
+  # order_reference: Your internal order reference
+  # order_info: Additional info about this order/transaction
+
+  class Operation
+
+    attr_accessor :auth_type, :currency, :settlement_day, :callback_url, :site_reference, :site_alias, :merchant_name,
+                  :order_reference, :order_info
+
+    def initialize(options={})
+      if !options.nil? && options.is_a?(Hash)
+        options.each do |key, value|
+          self.send("#{key}=", value) if self.respond_to? key
+        end
+      end
+    end
+
+    def add_to_xml(doc)
+      req = REXML::XPath.first(doc, "//Request")
+      req.attributes["Type"] = self.auth_type if self.auth_type
+      REXML::XPath.first(doc, "//SiteReference").text = self.site_reference if self.site_reference
+      ops = REXML::XPath.first(doc, "//Operation")
+      (ops.elements["Amount"] || ops.add_element("Amount")).text = self.amount if self.amount
+      (ops.elements["Currency"] || ops.add_element("Currency")).text = self.currency if self.currency
+      (ops.elements["MerchantName"] || ops.add_element("MerchantName")).text = self.merchant_name if self.merchant_name
+      (ops.elements["TermUrl"] || ops.add_element("TermUrl")).text = self.callback_url if self.callback_url
+      if (self.order_reference || self.order_info)
+        req.delete_element("Order")
+        order = req.add_element("Order")
+        order.add_element("OrderReference").add_text(self.order_reference) if self.order_reference
+        order.add_element("OrderInformation").add_text(self.order_info) if self.order_info
+      end
+      root = doc.root
+      (root.elements["Certificate"] || root.add_element("Certificate")).text = self.site_alias if self.site_alias
+    end
+
+    def amount=(new_val)
+      @amount = new_val.to_s
+    end
+
+    def amount
+      @amount
+    end
+  end
+end

data/lib/xpay/payment.rb

@@ -0,0 +1,209 @@
+module Xpay
+
+  # Payment Class handles all payment transaction AUTH, ST3DCARDQUERY and ST3DAUTH, also repeat transactions with ParentTransactionReference
+  # instantiated with p = Xpay::Payment.new(options)
+  # options is a Hash of the form keys creditcard, customer and operation
+  # there are several different options:
+  #
+  # Option 1: pass as hash options = {:creditcard => {}, :customer => {}, :operation => {}}
+  # in this case if the hash key is present and new CreditCard, Customer and Operation instance will be created from each hash and assigned to the class attributes
+  #
+  # Option 2: pass as Class instances of Xpay::CreditCard, Xpay::Customer and Xpay::Operation
+  # simply assigns it to class attributes
+  #
+  # Option 3: create with emtpy hash and use attribute accessors
+  # both as class and hash are possible
+  #
+  # It is not necessary to use the inbuilt classes Xpay::CreditCard, Xpay::Customer and Xpay::Operation,
+  # you can use your own classes (for example if you have an active_record CreditCard class.
+  # In this case your class(es) needs to implement a .add_to_xml method (best to copy the code from the gem classes)
+  #
+  # After initalization call the .make_payment method to process the payment
+  # return codes are as follows:
+
+
+  class Payment < Transaction
+    attr_reader :creditcard, :customer, :operation
+
+    def initialize(options={})
+      @request_xml = REXML::Document.new(Xpay.root_to_s)
+      self.creditcard = options[:creditcard] #.is_a?(Hash) ? Xpay::CreditCard.new(options[:creditcard]) : options[:creditcard]
+      self.customer = options[:customer].is_a?(Hash) ? Xpay::Customer.new(options[:customer]) : options[:customer]
+      self.operation = options[:operation].is_a?(Hash) ? Xpay::Operation.new(options[:operation]) : options[:operation]
+      create_from_xml(options[:xml], options[:pares] || nil) if options[:xml]
+      create_request
+    end
+
+    def creditcard=(v)
+      @creditcard = v.is_a?(Hash) ? Xpay::CreditCard.new(v) : v
+      create_request
+    end
+
+    def customer=(v)
+      @customer = v.is_a?(Hash) ? Xpay::Customer.new(v) : v
+      create_request
+    end
+
+    def operation=(v)
+      @operation = v.is_a?(Hash) ? Xpay::Operation.new(v) : v
+      create_request
+    end
+
+    # the make_payment method is where all the action is happening
+    # call it after you have initalized the Xpay::Payment class
+    # the following returns are possible:
+    #
+    # -1 a 3D Secure Authorisation is required, query your payment instance e.g. p.three_secure
+    # this will return a hash with all the necessary information to process the request further
+    # TODO provide further documentation for three_secure response block
+    #
+    # 0 Error in processing settlement request,
+    # query your instance e.g. p.response_block for further information
+    #
+    # 1 Settlement request approved,
+    # query your instance e.g. p.response_block for further information
+    #
+    # 2 Settlement request declined,
+    # query your instance e.g. p.response_block for further information
+
+    def make_payment
+      @response_xml = self.process()
+      if request_method=="ST3DCARDQUERY"
+        # In case the request was a ST3DCARDQUERY (the default case) the further processing depends on the respones. If it was an AUTH request than all is done and the response_xml gets processed
+        @response_xml = self.process() if response_code==0 # try once more if the response code is ZERO in ST3DCARDQUERY (According to securtrading tech support)
+        case response_code
+          when 1 # one means -> 3D AUTH required
+            rewrite_request_block() # Rewrite the request block with information from the response, deleting unused items
+
+            # If the card is enrolled in the scheme a redirect to a 3D Secure server is necessary, for this we need to store the request_xml in the database to be retrieved after the callback from the 3D secure Server and used to initialize a new payment object
+            # otherwise, if the card is not enrolled we just do a 3D AUTH straight away
+            if REXML::XPath.first(@response_xml, "//Enrolled").text == "Y"
+              rt = -1
+            else
+              # The Card is not enrolled and we do a 3D Auth request without going through a 3D Secure Server
+              # The PaRes element is required but empty as we did not go through a 3D Secure Server
+              threedsecure = REXML::XPath.first(@request_xml, "//ThreeDSecure")
+              pares = threedsecure.add_element("PaRes")
+              pares.text = ""
+              @response_xml = self.process()
+              rt = REXML::XPath.first(@response_xml, "//Result").text.to_i
+            end
+          when 2 # TWO -> do a normal AUTH request
+            rewrite_request_block("AUTH") # Rewrite the request block as AUTH request with information from the response, deleting unused items
+            @response_xml = self.process()
+            rt = REXML::XPath.first(@response_xml, "//Result").text.to_i
+          else # ALL other cases, payment declined
+            rt = REXML::XPath.first(@response_xml, "//Result").text.to_i
+        end
+      else
+        rt = REXML::XPath.first(@response_xml, "//Result").text.to_i
+      end
+      return rt
+    end
+
+    # The response_block is a hash and can have one of several values:
+    # the follwing values are always present after a transaction and can be queried to gain further details of the transaction:
+    #   * result_code:
+    #       0 for failure, check error_code for further details
+    #       1 transaction was succesful
+    #       2 transaction was denied
+    #   * security_response_code
+    #   * security_response_postcode
+    #   * transaction_reference
+    #   * transactionverifier
+    #   * transaction_time
+    #   * auth_code
+    #   * settlement_status
+    #   * error_code
+    def response_block
+      create_response_block
+    end
+
+    def three_secure
+      create_three_secure
+    end
+
+    private
+    def create_request
+      self.creditcard.add_to_xml(@request_xml) if self.creditcard.respond_to?(:add_to_xml)
+      self.customer.add_to_xml(@request_xml) if self.customer.respond_to?(:add_to_xml)
+      self.operation.add_to_xml(@request_xml) if self.operation.respond_to?(:add_to_xml)
+    end
+
+    #TODO function to create classes (Customer, CreditCard and Operation) from xml document
+    def create_from_xml(xml, pares)
+      raise PaResMissing.new "(2500) PaRes argument can not be omitted." if pares.nil?
+      @request_xml = REXML::Document.new xml
+      REXML::XPath.first(@request_xml, "//ThreeDSecure").add_element("PaRes").text=pares
+    end
+
+    def create_response_block
+      @response_xml.is_a?(REXML::Document) ?
+              {
+                      :result_code => (REXML::XPath.first(@response_xml, "//Result").text.to_i rescue nil),
+                      :security_response_code => (REXML::XPath.first(@response_xml, "//SecurityResponseSecurityCode").text.to_i rescue nil),
+                      :security_response_postcode => (REXML::XPath.first(@response_xml, "//SecurityResponsePostCode").text.to_i rescue nil),
+                      :security_response_address => (REXML::XPath.first(@response_xml, "//SecurityResponseAddress").text.to_i rescue nil),
+                      :transaction_reference => (REXML::XPath.first(@response_xml, "//TransactionReference").text rescue nil),
+                      :transactionverifier => (REXML::XPath.first(@response_xml, "//TransactionVerifier").text rescue nil),
+                      :transaction_time => (REXML::XPath.first(@response_xml, "//TransactionCompletedTimestamp").text rescue nil),
+                      :auth_code => (REXML::XPath.first(@response_xml, "//AuthCode").text rescue nil),
+                      :settlement_status => (REXML::XPath.first(@response_xml, "//SettleStatus").text.to_i rescue nil),
+                      :error_code => (REXML::XPath.first(@response_xml, "//Message").text rescue nil)
+              } : {}
+    end
+
+    def create_three_secure
+      @response_xml.is_a?(REXML::Document) ?
+              {
+                      :md => (REXML::XPath.first(@response_xml, "//MD").text rescue nil),
+                      :pareq => (REXML::XPath.first(@response_xml, "//PaReq").text rescue nil),
+                      :termurl => (REXML::XPath.first(@response_xml, "//TermUrl").text rescue nil),
+                      :acsurl =>  (REXML::XPath.first(@response_xml, "//AcsUrl").text rescue nil),
+                      :html =>  (REXML::XPath.first(@response_xml, "//Html").text rescue nil),
+                      :request_xml => (@request_xml.to_s rescue nil)
+              } : {}
+    end
+
+    # Rewrites the request according to the response coming from SecureTrading according to the required auth_type
+    # This only applies if the inital request was a ST3DCARDQUERY
+    # It deletes elements which are not needed for the subsequent request and
+    # adds the required additional information if an ST3DAUTH is needed
+    def rewrite_request_block(auth_type="ST3DAUTH")
+
+      # set the required AUTH type
+      REXML::XPath.first(@request_xml, "//Request").attributes["Type"] = auth_type
+
+      # delete term url and merchant name
+      op = REXML::XPath.first(@request_xml, "//Operation")
+      op.delete_element "TermUrl"
+      op.delete_element "MerchantName"
+
+      # delete accept and user agent in customer info
+      customer_info = REXML::XPath.first(@request_xml, "//CustomerInfo")
+      customer_info.delete_element "//Accept"
+      customer_info.delete_element "//UserAgent"
+
+      # delete credit card details and add TransactionVerifier and TransactionReference from response xml
+      # CC details are not needed anymore as verifier and reference are sufficient
+      cc_details = REXML::XPath.first(@request_xml, "//CreditCard")
+      cc_details.delete_element "//Number"
+      cc_details.delete_element "//Type"
+      trans_ver = cc_details.add_element("TransactionVerifier")
+      trans_ver.text = REXML::XPath.first(@response_xml, "//TransactionVerifier").text
+      trans_ref = cc_details.add_element("ParentTransactionReference")
+      trans_ref.text = REXML::XPath.first(@response_xml, "//TransactionReference").text
+
+      # unless it is an AUTH request, add additional required info for a 3DAUTH request
+      unless auth_type == "AUTH"
+        pm_method = REXML::XPath.first(@request_xml, "//PaymentMethod")
+        threedsecure = pm_method.add_element("ThreeDSecure")
+        enrolled = threedsecure.add_element("Enrolled")
+        enrolled.text = REXML::XPath.first(@response_xml, "//Enrolled").text
+        md = threedsecure.add_element("MD")
+        md.text = REXML::XPath.first(@response_xml, "//MD").text rescue ""
+      end
+      true
+    end
+  end
+end

data/lib/xpay/transaction.rb

@@ -0,0 +1,35 @@
+module Xpay
+  require 'socket'
+
+  # The transaction class is the parent class of all Transactions be it Payment, Refund or Paypal etc.
+  # it provides underlying methods which all transactions have in common
+  # It should not be instantiated by itself
+
+  class Transaction
+
+    attr_accessor :request_xml
+    attr_reader :three_secure, :response_xml, :response_block
+
+    def process()
+      a = TCPSocket.open("localhost", Xpay.config.port)
+      a.write(self.request_xml.to_s + "\n")
+      res = a.read()
+      a.close
+      # create an xml document, use everything from the start of <ResponseBlock to the end, discard header and status etc and return it
+      REXML::Document.new res[res.index("<ResponseBlock"), res.length]
+    end
+
+    def request_method
+      @request_method ||= REXML::XPath.first(@request_xml, "//Request").attributes["Type"]
+    end
+
+    def response_code
+      @response_code ||= REXML::XPath.first(@response_xml, "//Result").text.to_i rescue -1
+    end
+
+    private
+    def response_xml=(new_val)
+      @response_xml = new_val if new_val.is_a?(REXML::Document)
+    end
+  end
+end

data/lib/xpay/version.rb

@@ -0,0 +1,3 @@
+module Xpay
+  Version = '0.0.5'
+end

data/rails/init.rb

@@ -0,0 +1,2 @@
+require 'xpay'
+Xpay.load_config

data/tasks/xpay_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :xpay do
+#   # Task goes here
+# end

data/test/fixtures/config/xpay.yml

@@ -0,0 +1,25 @@
+# config/xpay.yml
+base: &base
+  port: 5000
+  merchant_name: Outlet Residential
+
+development:
+  <<: *base
+  alias: testoutlet12091
+  site_reference: testoutlet12091
+  version: "3.52"
+  port: 6000
+  callback_url: "http://127.0.0.1/callback"
+  default_query:  "AUTH"
+  settlement_day: "2"
+  default_currency: "USD"
+
+test:
+  <<: *base
+  alias: testoutlet12091
+  site_reference: testoutlet12091
+
+production:
+  <<: *base
+  alias: accommodationoutlet2538
+  site_reference: accommodationoutlet2538

data/test/fixtures/creditcards.yml

@@ -0,0 +1,37 @@
+base: &base
+  security_code: 123
+  valid_until: <%= Date.today.advance(:months => 3).strftime("%m/%y") %>
+
+class_test:
+  <<: *base
+  card_type: Visa
+  number: 4111111111111111
+  security_code: 123
+  valid_from: <%= Date.today.advance(:months => -5).strftime("%m/%y") %>
+  issue: "1"
+
+
+visa_no3d_auth:
+  <<: *base
+  card_type: Visa
+  number: 4111111111111111
+
+visa_no3d_decl:
+  <<: *base
+  card_type: Visa
+  number: 4242424242424242
+
+visa_3d_auth:
+  <<: *base
+  card_type: Visa
+  number: 4111111111111160
+
+master_no3d_auth:
+  <<: *base
+  card_type: Mastercard
+  number: 5111111111111118
+
+master_no3d_decl:
+  <<: *base
+  card_type: Mastercard
+  number: 5111111111111142

data/test/fixtures/customer.xml

@@ -0,0 +1 @@
+<?xml version='1.0' encoding='ISO-8859-1'?><RequestBlock Version='3.51'><Request Type='ST3DCARDQUERY'><Operation><SiteReference>site12345</SiteReference><MerchantName>CompanyName</MerchantName><TermUrl>http://localhost/gateway_callback</TermUrl></Operation><CustomerInfo><Postal><Name>JOE BLOGGS<NamePrefix>MR</NamePrefix><FirstName>Joe</FirstName><MiddleName>X</MiddleName><LastName>Bloggs</LastName><NameSuffix>PhD</NameSuffix></Name><Company>NotInventedHere.com</Company><Street>tonowhere crescent</Street><City>beyond the rainbow on stale bread</City><StateProv>East-West Swampshire</StateProv><PostalCode>X01 Z10</PostalCode><CountryCode>GB</CountryCode></Postal><Telecom><Phone>07950 843 363</Phone></Telecom><Online><Email>joe.x.bloggs@notinventedhere.com</Email></Online><Accept>text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8</Accept><UserAgent>Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.0; GTB5; Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1) ; SLCC1; .NET CLR 2.0.50727; Media Center PC 5.0; .NET CLR 3.0.04506; InfoPath.1; .NET4.0C; AskTbGLSV5/5.8.0.12304)</UserAgent></CustomerInfo></Request><Certificate>site12345</Certificate></RequestBlock>

data/test/fixtures/customer.yml

@@ -0,0 +1,22 @@
+class_test:
+  title: MR
+  fullname: JOE BLOGGS
+  firstname: Joe
+  lastname: Bloggs
+  middlename: X
+  namesuffix: PhD
+  companyname: NotInventedHere.com
+  street: tonowhere crescent
+  city: beyond the rainbow on stale bread
+  stateprovince: East-West Swampshire
+  postcode: X01 Z10
+  countrycode: GB
+  phone: 07950 843 363
+  email: joe.x.bloggs@notinventedhere.com
+  http_accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
+  user_agent: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.0; GTB5; Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1) ; SLCC1; .NET CLR 2.0.50727; Media Center PC 5.0; .NET CLR 3.0.04506; InfoPath.1; .NET4.0C; AskTbGLSV5/5.8.0.12304)"
+
+test_1:
+  fullname: V Pacher
+  http_accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
+  user_agent: "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.0; GTB5; Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1) ; SLCC1; .NET CLR 2.0.50727; Media Center PC 5.0; .NET CLR 3.0.04506; InfoPath.1; .NET4.0C; AskTbGLSV5/5.8.0.12304)"

data/test/fixtures/operation.xml

@@ -0,0 +1 @@
+<?xml version='1.0' encoding='ISO-8859-1'?><RequestBlock Version='3.51'><Request Type='AUTH'><Operation><SiteReference>site56987</SiteReference><MerchantName>TestMerchant</MerchantName><TermUrl>https://localhost/3dcallback</TermUrl><Amount>1000</Amount><Currency>USD</Currency></Operation><Order><OrderReference>TestOrder1245</OrderReference><OrderInformation>TestOrderInfo</OrderInformation></Order></Request><Certificate>site56987</Certificate></RequestBlock>

data/test/fixtures/operation.yml

@@ -0,0 +1,23 @@
+class_test:
+  auth_type: AUTH
+  currency: USD
+  amount: "1000"
+  settlement_day: "3"
+  callback_url: "https://localhost/3dcallback"
+  site_reference: site56987
+  site_alias: site56987
+  merchant_name: TestMerchant
+  order_reference: TestOrder1245
+  order_info: TestOrderInfo
+  port: 7000
+
+test_1:
+  auth_type: ST3DCARDQUERY
+  currency: GBP
+  amount: "1000"
+  settlement_day: "1"
+  site_reference: testoutlet12092
+  site_alias: testoutlet12092
+  callback_url: "https://localhost/3dcallback"
+  merchant_name: Outlet Residential
+  order_reference: TestOrder1245

data/test/fixtures/request_rewritten.xml

@@ -0,0 +1 @@
+<?xml version='1.0' encoding='ISO-8859-1'?><RequestBlock Version='3.51'><Request Type='ST3DAUTH'><Operation><SiteReference>site56987</SiteReference><Amount>1000</Amount><Currency>USD</Currency></Operation><PaymentMethod><CreditCard><StartDate>05/10</StartDate><ExpiryDate>01/11</ExpiryDate><SecurityCode>123</SecurityCode><Issue>1</Issue><TransactionVerifier>ArOH5um+qGhwLbuobJ5mdgzTr1qclm1j/qyG+VGDe9QSslGFXtwFA2A6jvM+qgUuZ0lLQPvJ82U1SkLOhm32dPRABlh0EkyrvKamrsDDRcsFZhWQLmS+yE0+keSaBq8C537NQAXIYcCYVvoOVKhDwdW4hZVfOtKFND+QxR2p89rw=</TransactionVerifier><ParentTransactionReference>17-9-1909368</ParentTransactionReference></CreditCard><ThreeDSecure><Enrolled>Y</Enrolled><MD>MTI4ODAwNjYzNi41MjAuMTc2MzczMzc3MDExMjg4MDA2NjM2LjUyMC4xNzYzNzMzNzcwMTEyODgwMDY2MzYuNTIwLjE3NjM3MzM3NzAxMTI4ODAwNjYzNi41MjAuMTc2MzczMzc3MDExMjg4MDA2NjM2LjUyMC4xNzYzNzMzNzcwMTEyODgwMDY2MzYuNTIwLjE3NjM3MzM3NzAxMTI4ODAwNjYzNi41MjAuMTc2MzczMzc3MDExMjg4MDA2NjM2LjUyMC4xNzYzNzMzNzcwMTEyODgwMDY2MzYuNTIwLjE3NjM3MzM3NzAxMTI4ODAwNjYzNi41MjAuMTc2MzczMzc3MDE=</MD></ThreeDSecure></PaymentMethod><CustomerInfo><Postal><Name>JOE BLOGGS<NamePrefix>MR</NamePrefix><FirstName>Joe</FirstName><MiddleName>X</MiddleName><LastName>Bloggs</LastName><NameSuffix>PhD</NameSuffix></Name><Company>NotInventedHere.com</Company><Street>tonowhere crescent</Street><City>beyond the rainbow on stale bread</City><StateProv>East-West Swampshire</StateProv><PostalCode>X01 Z10</PostalCode><CountryCode>GB</CountryCode></Postal><Telecom><Phone>07950 843 363</Phone></Telecom><Online><Email>joe.x.bloggs@notinventedhere.com</Email></Online></CustomerInfo><Order><OrderReference>TestOrder1245</OrderReference><OrderInformation>TestOrderInfo</OrderInformation></Order></Request><Certificate>site56987</Certificate></RequestBlock>

data/test/fixtures/response.xml

@@ -0,0 +1,9 @@
+<ResponseBlock Live='FALSE' Version='3.51'>
+  <Response Type='ST3DCARDQUERY'>
+    <OperationResponse>
+      <Message>(3100) Invalid ExpiryDate</Message>
+      <TransactionReference>17-9-1908322</TransactionReference>
+      <Result>0</Result>
+    </OperationResponse>
+  </Response>
+</ResponseBlock>