payment_express.rb in activemerchant-1.23.0

- old
+ new

@@ -18,11 +18,11 @@
       
       self.supported_countries = %w[ AU MY NZ SG ZA GB US ]
       
       self.homepage_url = 'http://www.paymentexpress.com/'
       self.display_name = 'PaymentExpress'
-      
+
       URL = 'https://sec.paymentexpress.com/pxpost.aspx'
       
       APPROVED = '1'
       
       TRANSACTIONS = {
@@ -32,27 +32,40 @@
         :capture        => 'Complete',
         :validate       => 'Validate'
       }
       
       # We require the DPS gateway username and password when the object is created.
+      #
+      # The PaymentExpress gateway also supports a :use_custom_payment_token boolean option.
+      # If set to true the gateway will use BillingId for the Token type.  If set to false,
+      # then the token will be sent as the DPS specified "DpsBillingId".  This is per the documentation at
+      # http://www.paymentexpress.com/technical_resources/ecommerce_nonhosted/pxpost.html#Tokenbilling
       def initialize(options = {})
-        # A DPS username and password must exist 
+        # A DPS username and password must exist
         requires!(options, :login, :password)
         # Make the options an instance variable
         @options = options
         super
       end
       
       # Funds are transferred immediately.
+      #
+      # `payment_source` can be a usual ActiveMerchant credit_card object, or can also
+      # be a string of the `DpsBillingId` or `BillingId` which can be gotten through the 
+      # store method.  If you are using a `BillingId` instead of `DpsBillingId` you must
+      # also set the instance method `#use_billing_id_for_token` to true, see the `#store`
+      # method for an example of how to do this.
       def purchase(money, payment_source, options = {})
         request = build_purchase_or_authorization_request(money, payment_source, options)
         commit(:purchase, request)      
       end
       
       # NOTE: Perhaps in options we allow a transaction note to be inserted
       # Verifies that funds are available for the requested card and amount and reserves the specified amount.
       # See: http://www.paymentexpress.com/technical_resources/ecommerce_nonhosted/pxpost.html#Authcomplete
+      #
+      # `payment_source` can be a usual ActiveMerchant credit_card object or a token, see #purchased method
       def authorize(money, payment_source, options = {})
         request = build_purchase_or_authorization_request(money, payment_source, options)
         commit(:authorization, request)
       end
       
@@ -74,22 +87,51 @@
       def credit(money, identification, options = {})
         deprecated CREDIT_DEPRECATION_MESSAGE
         refund(money, identification, options)
       end
       
-      # token based billing
-      
-      # initiates a "Validate" transcation to store card data on payment express servers
-      # returns a "token" that can be used to rebill this card
+      # Token Based Billing
+      # 
+      # Instead of storing the credit card details locally, you can store them inside the
+      # Payment Express system and instead bill future transactions against a token.
+      #
+      # This token can either be specified by your code or autogenerated by the PaymentExpress
+      # system.  The default is to let PaymentExpress generate the token for you and so use
+      # the `DpsBillingId`.  If you do not pass in any option of the `billing_id`, then the store
+      # method will ask PaymentExpress to create a token for you.  Additionally, if you are
+      # using the default `DpsBillingId`, you do not have to do anything extra in the
+      # initialization of your gateway object.
+      #
+      # To specify and use your own token, you need to do two things.
+      # 
+      # Firstly, pass in a `:billing_id` as an option in the hash of this store method.  No
+      # validation is done on this BillingId by PaymentExpress so you must ensure that it is unique.
+      #
+      #     gateway.store(credit_card, {:billing_id => 'YourUniqueBillingId'})
+      #
+      # Secondly, you will need to pass in the option `{:use_custom_payment_token => true}` when
+      # initializing your gateway instance, like so:
+      #
+      #     gateway = ActiveMerchant::Billing::PaymentExpressGateway.new(
+      #       :login    => 'USERNAME',
+      #       :password => 'PASSWORD',
+      #       :use_custom_payment_token => true
+      #     )
+      #
       # see: http://www.paymentexpress.com/technical_resources/ecommerce_nonhosted/pxpost.html#Tokenbilling
-      # PaymentExpress does not support unstoring a stored card.
+      #
+      # Note, once stored, PaymentExpress does not support unstoring a stored card.
       def store(credit_card, options = {})
         request  = build_token_request(credit_card, options)
         commit(:validate, request)
       end
-      
+    
       private
+
+      def use_custom_payment_token?
+        @options[:use_custom_payment_token]
+      end
       
       def build_purchase_or_authorization_request(money, payment_source, options)
         result = new_transaction      
 
         if payment_source.is_a?(String)
@@ -135,20 +177,25 @@
         xml.add_element("CardNumber").text = credit_card.number
         xml.add_element("DateExpiry").text = format_date(credit_card.month, credit_card.year)
         
         if credit_card.verification_value?
           xml.add_element("Cvc2").text = credit_card.verification_value
+          xml.add_element("Cvc2Presence").text = "1"
         end
         
         if requires_start_date_or_issue_number?(credit_card)
           xml.add_element("DateStart").text = format_date(credit_card.start_month, credit_card.start_year) unless credit_card.start_month.blank? || credit_card.start_year.blank?
           xml.add_element("IssueNumber").text = credit_card.issue_number unless credit_card.issue_number.blank?
         end
       end
-      
-      def add_billing_token(xml, token) 
-        xml.add_element("DpsBillingId").text = token
+
+      def add_billing_token(xml, token)
+        if use_custom_payment_token?
+          xml.add_element("BillingId").text = token
+        else
+          xml.add_element("DpsBillingId").text = token
+        end
       end
       
       def add_token_request(xml, options)
         xml.add_element("BillingId").text = options[:billing_id] if options[:billing_id]
         xml.add_element("EnableAddBillCard").text = 1
@@ -230,6 +277,6 @@
       def token
         @params["billing_id"] || @params["dps_billing_id"]
       end
     end
   end
-end
\ No newline at end of file
+end