breadmachine 0.0.0 → 0.0.1

data/README.rdoc

@@ -1,18 +1,62 @@
 = breadmachine
 
-Description goes here.
+Note the version number and consider very carefully whether you really need to
+use this code.
+
+Make dough with BreadMachine, a ruby interface for the SecureTrading XPay gateway.
+
+Should work with XPay v3.51 and v4.0.
+
+== Installation
+
+Until we get a config file going, make an initializer called breadmachine.rb
+in config/initializers, and stick the following into it:
+
+    BreadMachine::SecureTrading.configure do |config|
+      config.currency = 'GBP'
+      config.site_reference = 'yourxpaysitereference'
+      config.term_url = 'http://www.foo.com/your_callback_url'
+      config.merchant_name = "Hubbub"
+    end
+
+# TODO: check to see that this is absolutely true wrt currency
+config.currency: the standard ISO reference for your currency
+
+config.site_reference: provided to you by SecureTrading
+
+config.term_url: the resource that your ACS will post back to after a 3-D
+Secure authentication check.  If you decide to append any parameters to this
+when your callback executes (i.e. http://www.foo.com/your_callback_url/123-ordernumber)
+then remember to include a trailing slash on it - BreadMachine will just concatenate
+the values together.
+
+config.merchant_name: provided by SecureTrading
+
+== Glossary
+
+The terminology surrounding credit card payment systems is arcane and can cause
+a lot of confusion.  Here are some terms you might need to be familiar with:
+
+=== 3-D Secure
+
+The glorious credit card fraud prevention scheme beloved by web developers everywhere.
+
+=== 3-D Secure ACS
+
+This is the 3-D Secure Access Control Server, i.e. the 3-D Secure "verified by visa/mastercard" password page which you redirect your users to.
 
 == Note on Patches/Pull Requests
- 
+
 * Fork the project.
 * Make your feature addition or bug fix.
 * Add tests for it. This is important so I don't break it in a
   future version unintentionally.
 * Commit, do not mess with rakefile, version, or history.
   (if you want to have your own version, that is fine but
-   bump version in a commit by itself I can ignore when I pull)
+  bump version in a commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
 == Copyright
 
-Copyright (c) 2009 Matt Southerden. See LICENSE for details.
+Copyright (c) 2009 Matt Southerden, Dave Hrycyszyn. See LICENSE for details.
+

data/lib/breadmachine/dto/card.rb

@@ -1,9 +1,9 @@
 module BreadMachine
-  
+
+  # A data transfer object that represents the user's credit card.
+  #
   class Card
-    
-    include BreadMachine::SecureTrading::CardXml
-    
+
     attr_accessor :issuer
     attr_accessor :number
     attr_accessor :expiry_date
@@ -11,12 +11,26 @@ module BreadMachine
     attr_accessor :issue
     attr_accessor :security_code
     attr_accessor :transaction_verifier
-    attr_accessor :parent_transaction_reference
-    
+    attr_accessor :transaction_reference
+
+    # Required properties include :issuer, :number, and :expiry_date.
+    #
+    # :issuer should be a downcased string ("amex", "visa", "mastercard")
+    # :number should be an integer
+    # :expiry_date should be a string in the format "mm/yy"
+    #
+    # :issue is required for Solo cards.
+    # :start_date is required for "some" cards. The XPay spec says "for a full
+    #   list of cards requiring start_date, please contact your acquiring bank".
+    #
+    # TODO: make expiry_date and start_date into Date objects to save crappy
+    # string munging.
+    #
     def initialize(attributes = {})
       attributes.each { |key, value| send("#{key}=", value) }
     end
-    
+
   end
-  
-end
+
+end
+

data/lib/breadmachine/dto/customer_info.rb

@@ -1,16 +1,30 @@
 module BreadMachine
-    
+
+  # Billing details for customer.  This is used by XPay and the acquiring banks
+  # to keep an audit trail for fraud prevention purposes, so it's necessary for
+  # some kinds of auth queries (e.g. AVS checks).
+  #
   class CustomerInfo
-    
+
     attr_accessor :name_prefix, :first_name, :middle_name, :last_name, :name_suffix,
                   :company, :street, :city, :state, :postcode, :iso_2_country,
                   :telephone, :email,
                   :accept, :user_agent
-    
+
+    # XPay doesn't require any of this info for regular transactions, but if
+    # you've got your XPay system set up to decline if an AVS check fails, you'd
+    # better include it.
+    #
+    # 3-D Secure card enrollment checks *require* :user_agent and :accept
+    #
+    # The XPay API reference strongly recommends that all of this info is filled
+    # in, regardless of what kind of API call you're making.
+    #
     def initialize(attributes = {})
       attributes.each { |key, value| send("#{key}=", value) }
     end
-    
+
   end
-    
+
 end
+

data/lib/breadmachine/dto/order_info.rb

@@ -1,13 +1,26 @@
 module BreadMachine
-    
+
+  # Order reference information for auditing purposes.
+  #
   class OrderInfo
-    
+
     attr_accessor :order_reference, :order_information
-    
+
+    # It is strongly advised that these properties are included in transactions,
+    # but they are not required.
+    #
+    # Suggested usage:
+    #
+    # :order_reference should be something like the order or invoice number.
+    # :order_information could be the first 255 characters of the names of the
+    #    items in the order (as an example) - basically anything that can
+    #    identify an order in a human-friendly way.
+    #
     def initialize(attributes = {})
       attributes.each { |key, value| send("#{key}=", value) }
     end
-    
+
   end
-    
+
 end
+

data/lib/breadmachine/extensions/string.rb

@@ -0,0 +1,11 @@
+class String
+  
+  def indent(n)
+    if n >= 0
+      gsub(/^/, ' ' * n)
+    else
+      gsub(/^ {0,#{-n}}/, "")
+    end
+  end
+  
+end

data/lib/breadmachine/extensions.rb

@@ -1 +1,2 @@
-require 'breadmachine/extensions/money'
+require 'breadmachine/extensions/money'
+require 'breadmachine/extensions/string'

data/lib/breadmachine/secure_trading/auth_request.rb

@@ -3,9 +3,11 @@ module BreadMachine
     
     class AuthRequest
       
-      def initialize(amount, card, customer_info, order_info, settlement_day = 1)
+      def initialize(amount, card, customer_info, order_info, settlement_day)
+        raise ArgumentError, 'Currency mismatch' unless amount.currency == BreadMachine::SecureTrading::configuration.currency
+        
         @amount = amount
-        @card = card
+        @card = BreadMachine::SecureTrading::CardXml.new(card)
         @customer_info = BreadMachine::SecureTrading::CustomerInfoAuthXml.new(customer_info)
         @order_info = BreadMachine::SecureTrading::OrderInfoXml.new(order_info)
         @settlement_day = settlement_day

data/lib/breadmachine/secure_trading/auth_reversal_request.rb

@@ -3,14 +3,13 @@ module BreadMachine
     
     class AuthReversalRequest
       
-      def initialize(transaction, customer_info, order_info)
+      def initialize(transaction, order_info)
         @transaction = transaction
-        @customer_info = BreadMachine::SecureTrading::CustomerInfoAuthXml.new(customer_info)
         @order_info = BreadMachine::SecureTrading::OrderInfoXml.new(order_info)
       end
       
       def response(xml)
-        St3dAuthResponse.new(xml)
+        AuthReversalResponse.new(xml)
       end
       
       def to_xml
@@ -19,14 +18,13 @@ module BreadMachine
           xml.Operation {
             xml.SiteReference BreadMachine::SecureTrading::configuration.site_reference
           }
-          # xml << @customer_info.to_xml
           xml.PaymentMethod {
             xml.CreditCard {
               xml.ParentTransactionReference @transaction.transaction_reference
               xml.TransactionVerifier @transaction.transaction_verifier
             }
           }
-          # xml << @order_info.to_xml
+          xml << @order_info.to_xml
         }
       end
       

data/lib/breadmachine/secure_trading/auth_reversal_response.rb

@@ -1,6 +1,11 @@
 module BreadMachine
   module SecureTrading
-    class AuthReversalResponse
+    class AuthReversalResponse < XpayResponse
+      
+      def successful?
+        self.result == '1'
+      end
+      
     end
   end
 end

data/lib/breadmachine/secure_trading/card_xml.rb

@@ -1,19 +1,23 @@
 module BreadMachine
   module SecureTrading
 
-    module CardXml
+    class CardXml
+      
+      def initialize(card)
+        @card = card
+      end
       
       def to_xml
         xml = Builder::XmlMarkup.new(:indent => 2)
         xml.CreditCard {
-          xml.Type @issuer
-          xml.Number @number
-          xml.ExpiryDate @expiry_date
-          xml.StartDate @start_date
-          xml.Issue @issue
-          xml.SecurityCode @security_code
-          xml.TransactionVerifier @transaction_verifier
-          xml.ParentTransactionReference @parent_transaction_reference
+          xml.Type @card.issuer unless @card.issuer.blank?
+          xml.Number @card.number unless @card.number.blank?
+          xml.ExpiryDate @card.expiry_date unless @card.expiry_date.blank?
+          xml.StartDate @card.start_date unless @card.start_date.blank?
+          xml.Issue @card.issue unless @card.issue.blank?
+          xml.SecurityCode @card.security_code unless @card.security_code.blank?
+          xml.TransactionVerifier @card.transaction_verifier unless @card.transaction_verifier.blank?
+          xml.ParentTransactionReference @card.transaction_reference unless @card.transaction_reference.blank?
         }
       end
       

data/lib/breadmachine/secure_trading/payment_methods.rb

@@ -1,13 +1,24 @@
 module BreadMachine
   module SecureTrading
-    
+
     module PaymentMethods
-      
+
       def auth(*args)
         request = SecureTrading::AuthRequest.new(*args)
         return SecureTrading::XPay.exchange(request)
       end
-      
+
+      def repeat_auth(*args)
+        request = SecureTrading::AuthRequest.new(*args)
+        return SecureTrading::XPay.exchange(request)
+      end
+
+      # Checks to see whether a card is enrolled in 3-D Secure. Returns a
+      # ST3DCardQueryResponse which can tell us whether the card is enrolled
+      # and what kind of authorisation to perform.
+      #
+      # Arguments are: amount, creditcard, customer_info, order_info
+      #
       def three_d_secure_enrolled?(*args)
         request = SecureTrading::St3dCardQueryRequest.new(*args)
         return SecureTrading::XPay.exchange(request)
@@ -17,12 +28,13 @@ module BreadMachine
         request = SecureTrading::St3dAuthRequest.new(*args)
         return SecureTrading::XPay.exchange(request)
       end
-      
+
       def reverse(*args)
         request = SecureTrading::AuthReversalRequest.new(*args)
         return SecureTrading::XPay.exchange(request)
       end
     end
-    
+
   end
-end
+end
+

data/lib/breadmachine/secure_trading/st_3d_auth_request.rb

@@ -1,22 +1,43 @@
 module BreadMachine
   module SecureTrading
-    
+
     class St3dAuthRequest
-      
-      def initialize(amount, card, customer_info, order_info, three_d_secure, settlement_day = 1)
+
+      # A 3-D Secure auth reqeust to ask XPay to reserve funds at an acquiring
+      # bank, checking whether this card has funds available to cover the given
+      # amount.
+      #
+      # Although XPay doesn't absolutely require all of the order
+      # information etc., BreadMachine does as it's better for history tracking
+      # and is strongly recommended by XPay.
+      #
+      # settlement_day allows you to tell XPay when the auth request should be
+      # queued for settlement.  The default, 1 day, will automatically tell
+      # SecureTrading to settle the amount on the day after the auth request.
+      # Note that even if you pass nil to settlement_day, the standard behaviour
+      # of XPay is to queue the auth request for settlement 1 day after the auth
+      # request.  Passing a settlement_day of 0 will tell XPay not to settle
+      # without manual intervention.
+      #
+      def initialize(amount, card, customer_info, order_info, three_d_secure, settlement_day)
+        raise ArgumentError, 'Currency mismatch' unless amount.currency == BreadMachine::SecureTrading::configuration.currency
+
         @amount = amount
-        @card = card
-        @card.parent_transaction_reference = three_d_secure.transaction_reference
+        @card = BreadMachine::SecureTrading::CardXml.new(card)
         @customer_info = BreadMachine::SecureTrading::CustomerInfoAuthXml.new(customer_info)
         @order_info = BreadMachine::SecureTrading::OrderInfoXml.new(order_info)
         @three_d_secure = BreadMachine::SecureTrading::ThreeDSecureCredentialsXml.new(three_d_secure)
         @settlement_day = settlement_day
       end
-      
+
+      # The specific response for this request to the XPay daemon.
+      #
       def response(xml)
         St3dAuthResponse.new(xml)
       end
-      
+
+      # Generate the expected XML for this XPay request.
+      #
       def to_xml
         xml = Builder::XmlMarkup.new(:indent => 2)
         xml.Request("Type" => "ST3DAUTH") {
@@ -34,8 +55,9 @@ module BreadMachine
           xml << @order_info.to_xml
         }
       end
-      
+
     end
-    
+
   end
-end
+end
+

data/lib/breadmachine/secure_trading/st_3d_auth_response.rb

@@ -1,25 +1,34 @@
 module BreadMachine
   module SecureTrading
-    
-    class St3dAuthResponse
-      
-      def initialize(xml)
-        @xml = Nokogiri::XML.parse(xml)
-      end
-      
+
+    # A response object which tells us what happened with a 3-D Secure
+    # AUTH request.
+    #
+    class St3dAuthResponse < XpayResponse
+
+      # Returns true if the AUTH request was successful, i.e. if the funds were
+      # successfully reserved.
+      #
       def successful?
         @xml.xpath('//OperationResponse/Result').text == "1"
       end
       
+      def declined?
+        @xml.xpath('//OperationResponse/Result').text == "2"
+      end
+
+      # A unique identifier for this AUTH transaction.
+      #
       def transaction_reference
         @xml.xpath('//OperationResponse/TransactionReference').text
       end
-      
+
       def transaction_verifier
         @xml.xpath('//OperationResponse/TransactionVerifier').text
       end
-      
+
     end
-    
+
   end
-end
+end
+

data/lib/breadmachine/secure_trading/st_3d_card_query_request.rb

@@ -1,19 +1,27 @@
 module BreadMachine
   module SecureTrading
-    
+
+    # A 3-D Secure query to figure out whether a given card is enrolled in
+    # 3-D Secure.  Although XPay doesn't absolutely require all of the order
+    # information etc., BreadMachine does as it's better for history tracking
+    # and is strongly recommended by XPay.
+    #
     class St3dCardQueryRequest
-      
-      def initialize(amount, card, customer_info, order_info)
+
+      def initialize(amount, card, customer_info, order_info, options = {})
+        raise ArgumentError, 'Currency mismatch' unless amount.currency == BreadMachine::SecureTrading::configuration.currency
+
         @amount = amount
         @customer_info = BreadMachine::SecureTrading::CustomerInfoEnrolmentXml.new(customer_info)
         @order_info = BreadMachine::SecureTrading::OrderInfoXml.new(order_info)
-        @card = card
+        @card = BreadMachine::SecureTrading::CardXml.new(card)
+        @options = options
       end
-      
+
       def response(xml)
         St3dCardQueryResponse.new(xml)
       end
-      
+
       def to_xml
         xml = Builder::XmlMarkup.new(:indent => 2)
         xml.Request("Type" => "ST3DCARDQUERY") {
@@ -21,7 +29,7 @@ module BreadMachine
             xml.Amount @amount.cents
             xml.Currency BreadMachine::SecureTrading::configuration.currency
             xml.SiteReference BreadMachine::SecureTrading::configuration.site_reference
-            xml.TermUrl BreadMachine::SecureTrading::configuration.term_url
+            xml.TermUrl self.term_url
             xml.MerchantName BreadMachine::SecureTrading::configuration.merchant_name
           }
           xml << @customer_info.to_xml
@@ -31,7 +39,18 @@ module BreadMachine
           xml << @order_info.to_xml
         }
       end
+      
+      protected
+      
+      def term_url
+        if @options.key?(:term_url_append)
+          BreadMachine::SecureTrading::configuration.term_url + @options[:term_url_append]
+        else
+          BreadMachine::SecureTrading::configuration.term_url
+        end
+      end
     end
-    
+
   end
-end
+end
+

data/lib/breadmachine/secure_trading/st_3d_card_query_response.rb

@@ -1,46 +1,145 @@
 module BreadMachine
   module SecureTrading
-    
-    class St3dCardQueryResponse
-      
-      def initialize(xml)
-        @xml = Nokogiri::XML.parse(xml)
-      end
-      
+
+    # A response object which tells us what happened with a 3-D Secure
+    # enrollment check.
+    #
+    class St3dCardQueryResponse < XpayResponse
+
+      # Checks whether the request was successfully processed.  A true response
+      # does not necessarily mean anything other than the XPay service
+      # acknowledged that it has talked to you successfully.
+      #
+      # From the XPay docs:
+      # self.result '2' means "the request was successfully processed but the
+      # 3-D Secure process cannot be continued".  This would happen in the case
+      # of a credit card provider which is not participating in 3-D Secure.
+      #
       def successful?
-        @xml.xpath('//OperationResponse/Result').text == "1"
+        self.result == '1' || self.result == '2'
       end
-      
+
+      # Is the card enrolled in 3-D Secure?
+      #
+      # Returns "Y", "N", "U", "N/A"
+      #
+      # From our reading of the XPay documentation,
+      # N/A (not available) will be returned in cases where the result is an error.
+      # N (no) will be returned if the card is not currently enrolled.
+      # U (unknown) will be returned in cases where the credit card provider
+      #   returns an ambiguous response to the enrollment check.  You should
+      #   redirect the  user to a 3-D Secure auth check page in this case.
+      # Y (yes) will be returned if the card is enrolled. You should redirect the
+      #   user to a 3-D Secure auth check page in this case.
+      #
       def enrolled
-        {
-          'N/A' => :na,
-          'Y'   => :yes,
-          'N'   => :no,
-          'U'   => :unknown
-        }[@xml.xpath('//OperationResponse/Enrolled').text]
+        @xml.xpath('//OperationResponse/Enrolled').text
       end
-      
+
+      # If this is true, you should redirect your user to a 3-D Secure access
+      # control server (ACS) page.
+      #
+      # Result = 1 from the card enrollment query means that the card issuer is
+      # part of 3-D Secure and that a 3-D Secure auth should be performed.
+      #
+      # Enrolled = "Y" means that the card is enrolled in 3-D Secure and that
+      # the user should be redirected to ACS to authenticate.
+      #
+      def three_d_auth_with_redirect?
+        self.result == "1" && enrolled == "Y"
+      end
+
+      # If a card provider is part of 3D-Secure but the card is not enrolled,
+      # it is still necessary to do a 3-D Secure auth request for funds even
+      # though we do not need to redirect the user to the ACS server.
+      #
+      def three_d_auth_without_redirect?
+        self.result == "1" && enrolled != "Y"
+      end
+
+      # If this returns true, you can perform a regular auth check for funds.
+      #
+      def normal_auth?
+        self.result != "1"
+      end
+
+      # A unique reference generated according to the 3-D Secure specification
+      # (currently up to 1024 bytes in base64 format). It will be returned to
+      # the merchant in the case of receiving an <Enrolled> of Y. This can be
+      # used by the merchant to tie up a response obtained from an ACS after the
+      # customer’s authentication process.
+      #
       def md
         @xml.xpath('//OperationResponse/MD').text
       end
-      
+
+      # The pa_req contains purchase transaction details upon which ACS
+      #  authentication decisions are based.
+      #
+      # If you are making your own customised redirect page instead of using
+      # the <Html> provided then this field MUST be included in that html, as a
+      # hidden field.
+      #
       def pa_req
         @xml.xpath('//OperationResponse/PaReq').text
       end
-      
+
+      # The URL of the 3-D Secure ACS page (see README) to redirect to.
+      #
       def acs_url
         @xml.xpath('//OperationResponse/AcsUrl').text
       end
       
+      # The URL which the ACS will send the user to after they have
+      # authenticated.
+      #
+      # This is informational as you passed it in so hopefully you know what it
+      # is. ;)
+      #
+      def term_url
+        @xml.xpath('//OperationResponse/TermUrl').text
+      end
+
       def transaction_reference
         @xml.xpath('//OperationResponse/TransactionReference').text
       end
-      
+
+      def transaction_verifier
+        @xml.xpath('//OperationResponse/TransactionVerifier').text
+      end
+
       def auth_type
-        BreadMachine::SecureTrading::St3dAuthRequest
+        self.result == '1' ?
+          BreadMachine::SecureTrading::St3dAuthRequest :
+          BreadMachine::SecureTrading::AuthRequest
       end
-      
+
+
+      # The ACS HTML POST form returned by the request.  This is an extremely
+      # ugly html page containing all of the form parameters needed to identify
+      # the user for a 3-D Secure authentication check.  It's possible (and
+      # probably desirable) to make your own page and style it how you want,
+      # including the same parameters, but this page is a good first step
+      # during integration.
+      #
+      # If you need to redirect a user to the 3-D Secure ACS page, you can do
+      # something like
+      #
+      #  if response.should_redirect?
+      #    render :text => CGI.unescape(response.html)
+      #  end
+      #
+      # The returned HTML contains a javascript call which will submit the form
+      # automatically with the correct POST parameters for this request (or
+      # display an ugly HTML page telling the user to click to redirect to
+      # 3-D Secure).
+      #
+      def html
+        @xml.xpath('//OperationResponse/Html').text
+      end
+
     end
-    
+
   end
-end
+end
+