start_activemerchant 1.50.0

data/lib/active_merchant/billing/gateways/payflow/payflow_express_response.rb

@@ -0,0 +1,39 @@
+module ActiveMerchant #:nodoc:
+  module Billing #:nodoc:
+    class PayflowExpressResponse < Response
+      def email
+        @params['e_mail']
+      end
+      
+      def full_name
+        "#{@params['name']} #{@params['lastname']}"
+      end
+      
+      def token
+        @params['token']
+      end
+      
+      def payer_id
+        @params['payer_id']
+      end
+      
+      # Really the shipping country, but it is all the information provided
+      def payer_country
+        address['country']
+      end
+      
+      def address
+        {  'name'       => full_name,
+           'company'    => nil,
+           'address1'   => @params['street'],
+           'address2'   => @params['shiptostreet2'] || @params['street2'],
+           'city'       => @params['city'],
+           'state'      => @params['state'],
+           'country'    => @params['country'],
+           'zip'        => @params['zip'],
+           'phone'      => nil
+        }
+      end
+    end
+  end
+end

data/lib/active_merchant/billing/gateways/payflow/payflow_response.rb

@@ -0,0 +1,13 @@
+module ActiveMerchant #:nodoc:
+  module Billing #:nodoc:
+    class PayflowResponse < Response
+      def profile_id
+        @params['profile_id']
+      end
+      
+      def payment_history
+        @payment_history ||= @params['rp_payment_result'].collect{ |result| result.stringify_keys } rescue []
+      end
+    end
+  end
+end

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

@@ -0,0 +1,224 @@
+require 'active_merchant/billing/gateways/payflow/payflow_common_api'
+require 'active_merchant/billing/gateways/payflow/payflow_express_response'
+require 'active_merchant/billing/gateways/paypal_express_common'
+
+module ActiveMerchant #:nodoc:
+  module Billing #:nodoc:
+      # ==General Parameters
+      # The following parameters are supported for #setup_authorization, #setup_purchase, #authorize and #purchase transactions. I've read
+      # in the docs that they recommend you pass the exact same parameters to both setup and authorize/purchase.
+      #
+      # This information was gleaned from a mix of:
+      # * PayFlow documentation
+      #   * for key value pairs: {Express Checkout for Payflow Pro (PDF)}[https://cms.paypal.com/cms_content/US/en_US/files/developer/PFP_ExpressCheckout_PP.pdf]
+      #   * XMLPay: {Payflow Pro XMLPay Developer's Guide (PDF)}[https://cms.paypal.com/cms_content/US/en_US/files/developer/PP_PayflowPro_XMLPay_Guide.pdf]
+      # * previous ActiveMerchant code
+      # * trial & error
+      #
+      # The following parameters are currently supported.
+      # [<tt>:ip</tt>] (opt) Customer IP Address
+      # [<tt>:order_id</tt>] (opt) An order or invoice number. This will be passed through to the Payflow backend at manager.paypal.com, and show up as "Supplier Reference #"
+      # [<tt>:description</tt>] (opt) Order description, shown to buyer (after redirected to PayPal). If Order Line Items are used (see below), then the description is suppressed. This will not be passed through to the Payflow backend.
+      # [<tt>:billing_address</tt>] (opt) See ActiveMerchant::Billing::Gateway for details
+      # [<tt>:shipping_address</tt>] (opt) See ActiveMerchant::Billing::Gateway for details
+      # [<tt>:currency</tt>] (req) Currency of transaction, will be set to USD by default for PayFlow Express if not specified
+      # [<tt>:email</tt>] (opt) Email of buyer; used to pre-fill PayPal login screen
+      # [<tt>:payer_id</tt>] (opt) Unique PayPal buyer account identification number, as returned by details_for request
+      # [<tt>:token</tt>] (req for #authorize & #purchase) Token returned by setup transaction
+      # [<tt>:no_shipping</tt>] (opt) Boolean for whether or not to display shipping address to buyer
+      # [<tt>:address_override</tt>] (opt) Boolean. If true, display shipping address passed by parameters, rather than shipping address on file with PayPal
+      # [<tt>:allow_note</tt>] (opt) Boolean for permitting buyer to add note during checkout. Note contents can be retrieved with details_for transaction
+      # [<tt>:return_url</tt>] (req) URL to which the buyer’s browser is returned after choosing to pay.
+      # [<tt>:cancel_return_url</tt>] (req) URL to which the buyer is returned if the buyer cancels the order.
+      # [<tt>:notify_url</tt>] (opt) Your URL for receiving Instant Payment Notification (IPN) about this transaction.
+      # [<tt>:comment</tt>] (opt) Comment field which will be reported to Payflow backend (at manager.paypal.com) as Comment1
+      # [<tt>:comment2</tt>] (opt) Comment field which will be reported to Payflow backend (at manager.paypal.com) as Comment2
+      # [<tt>:discount</tt>] (opt) Total discounts in cents
+      #
+      # ==Line Items
+      # Support for order line items is available, but has to be enabled on the PayFlow backend. This is what I was told by Todd Sieber at Technical Support:
+      #
+      # <em>You will need to call Payflow Support at 1-888-883-9770, choose option #2.  Request that they update your account in "Pandora" under Product Settings >> PayPal Mark and update the Features Bitmap to 1111111111111112.  This is 15 ones and a two.</em>
+      #
+      # See here[https://www.x.com/message/206214#206214] for the forum discussion (requires login to {x.com}[https://x.com]
+      #
+      # [<tt>:items</tt>] (opt) Array of Order Line Items hashes. These are shown to the buyer after redirect to PayPal.
+      #
+      #
+      #
+      #                   The following keys are supported for line items:
+      #                   [<tt>:name</tt>] Name of line item
+      #                   [<tt>:description</tt>] Description of line item
+      #                   [<tt>:amount</tt>] Line Item Amount in Cents (as Integer)
+      #                   [<tt>:quantity</tt>] Line Item Quantity (default to 1 if left blank)
+      #
+      # ====Customization of Payment Page
+      # [<tt>:page_style</tt>] (opt) Your URL for receiving Instant Payment Notification (IPN) about this transaction.
+      # [<tt>:header_image</tt>] (opt) Your URL for receiving Instant Payment Notification (IPN) about this transaction.
+      # [<tt>:background_color</tt>] (opt) Your URL for receiving Instant Payment Notification (IPN) about this transaction.
+      # ====Additional options for old Checkout Experience, being phased out in 2010 and 2011
+      # [<tt>:header_background_color</tt>] (opt) Your URL for receiving Instant Payment Notification (IPN) about this transaction.
+      # [<tt>:header_border_color</tt>] (opt) Your URL for receiving Instant Payment Notification (IPN) about this transaction.
+
+
+    class PayflowExpressGateway < Gateway
+      include PayflowCommonAPI
+      include PaypalExpressCommon
+
+      self.test_redirect_url = 'https://www.sandbox.paypal.com/cgi-bin/webscr'
+      self.homepage_url = 'https://www.paypal.com/cgi-bin/webscr?cmd=xpt/merchant/ExpressCheckoutIntro-outside'
+      self.display_name = 'PayPal Express Checkout'
+
+      def authorize(money, options = {})
+        requires!(options, :token, :payer_id)
+        request = build_sale_or_authorization_request('Authorization', money, options)
+        commit(request, options)
+      end
+
+      def purchase(money, options = {})
+        requires!(options, :token, :payer_id)
+        request = build_sale_or_authorization_request('Sale', money, options)
+        commit(request, options)
+      end
+
+      def refund(money, identification, options = {})
+        request = build_reference_request(:credit, money, identification, options)
+        commit(request, options)
+      end
+
+      def credit(money, identification, options = {})
+        ActiveMerchant.deprecated CREDIT_DEPRECATION_MESSAGE
+        refund(money, identification, options)
+      end
+
+      def setup_authorization(money, options = {})
+        requires!(options, :return_url, :cancel_return_url)
+
+        request = build_setup_express_sale_or_authorization_request('Authorization', money, options)
+        commit(request, options)
+      end
+
+      def setup_purchase(money, options = {})
+        requires!(options, :return_url, :cancel_return_url)
+
+        request = build_setup_express_sale_or_authorization_request('Sale', money, options)
+        commit(request, options)
+      end
+
+      def details_for(token)
+        request = build_get_express_details_request(token)
+        commit(request, options)
+      end
+
+      private
+      def build_get_express_details_request(token)
+        xml = Builder::XmlMarkup.new :indent => 2
+        xml.tag! 'GetExpressCheckout' do
+          xml.tag! 'Authorization' do
+            xml.tag! 'PayData' do
+              xml.tag! 'Tender' do
+                xml.tag! 'PayPal' do
+                  xml.tag! 'Token', token
+                end
+              end
+            end
+          end
+        end
+        xml.target!
+      end
+
+      def build_setup_express_sale_or_authorization_request(action, money, options = {})
+        xml = Builder::XmlMarkup.new :indent => 2
+        xml.tag! 'SetExpressCheckout' do
+          xml.tag! action do
+            add_pay_data xml, money, options
+          end
+        end
+        xml.target!
+      end
+
+      def build_sale_or_authorization_request(action, money, options)
+        xml = Builder::XmlMarkup.new :indent => 2
+        xml.tag! 'DoExpressCheckout' do
+          xml.tag! action do
+            add_pay_data xml, money, options
+          end
+        end
+        xml.target!
+      end
+
+      def add_pay_data(xml, money, options)
+        xml.tag! 'PayData' do
+          xml.tag! 'Invoice' do
+            xml.tag! 'CustIP', options[:ip] unless options[:ip].blank?
+            xml.tag! 'InvNum', options[:order_id] unless options[:order_id].blank?
+            # Description field will be shown to buyer, unless line items are also being supplied (then only line items are shown).
+            xml.tag! 'Description', options[:description] unless options[:description].blank?
+            # Comment, Comment2 should make it to the backend at manager.paypal.com, as with Payflow credit card transactions
+            # but that doesn't seem to work (yet?). See: https://www.x.com/thread/51908?tstart=0
+            xml.tag! 'Comment', options[:comment] unless options[:comment].nil?
+            xml.tag!('ExtData', 'Name'=> 'COMMENT2', 'Value'=> options[:comment2]) unless options[:comment2].nil?
+
+            billing_address = options[:billing_address] || options[:address]
+            add_address(xml, 'BillTo', billing_address, options) if billing_address
+            add_address(xml, 'ShipTo', options[:shipping_address], options) if options[:shipping_address]
+
+            # Note: To get order line-items to show up with Payflow Express, this feature has to be enabled on the backend.
+            # Call Support at 888 883 9770, press 2. Then request that they update your account in "Pandora" under Product Settings >> PayPal
+            # Mark and update the Features Bitmap to 1111111111111112.  This is 15 ones and a two.
+            # See here for the forum discussion: https://www.x.com/message/206214#206214
+            items = options[:items] || []
+            items.each_with_index do |item, index|
+              xml.tag! 'ExtData', 'Name' => "L_DESC#{index}", 'Value' => item[:description]
+              xml.tag! 'ExtData', 'Name' => "L_COST#{index}", 'Value' => amount(item[:amount])
+              xml.tag! 'ExtData', 'Name' => "L_QTY#{index}", 'Value' => item[:quantity] || '1'
+              xml.tag! 'ExtData', 'Name' => "L_NAME#{index}", 'Value' => item[:name]
+              # Note: An ItemURL is supported in Paypal Express (different API), but not PayFlow Express, as far as I can tell.
+              # L_URLn nor L_ITEMURLn seem to work
+            end
+            if items.any?
+              xml.tag! 'ExtData', 'Name' => 'CURRENCY', 'Value' => options[:currency] || currency(money)
+              xml.tag! 'ExtData', 'Name' => "ITEMAMT", 'Value' => amount(options[:subtotal] || money)
+            end
+            xml.tag! 'DiscountAmt', amount(options[:discount]) if options[:discount]
+            xml.tag! 'TotalAmt', amount(money), 'Currency' => options[:currency] || currency(money)
+
+          end
+
+          xml.tag! 'Tender' do
+            add_paypal_details(xml, options)
+          end
+        end
+      end
+
+      def add_paypal_details(xml, options)
+         xml.tag! 'PayPal' do
+          xml.tag! 'EMail', options[:email] unless options[:email].blank?
+          xml.tag! 'ReturnURL', options[:return_url] unless options[:return_url].blank?
+          xml.tag! 'CancelURL', options[:cancel_return_url] unless options[:cancel_return_url].blank?
+          xml.tag! 'NotifyURL', options[:notify_url] unless options[:notify_url].blank?
+          xml.tag! 'PayerID', options[:payer_id] unless options[:payer_id].blank?
+          xml.tag! 'Token', options[:token] unless options[:token].blank?
+          xml.tag! 'NoShipping', options[:no_shipping] ? '1' : '0'
+          xml.tag! 'AddressOverride', options[:address_override] ? '1' : '0'
+          xml.tag! 'ButtonSource', application_id.to_s.slice(0,32) unless application_id.blank?
+
+          # Customization of the payment page
+          xml.tag! 'PageStyle', options[:page_style] unless options[:page_style].blank?
+          xml.tag! 'HeaderImage', options[:header_image] unless options[:header_image].blank?
+          xml.tag! 'PayflowColor', options[:background_color] unless options[:background_color].blank?
+          # Note: HeaderImage and PayflowColor apply to both the new (as of 2010) and the old checkout experience
+          # HeaderBackColor and HeaderBorderColor apply only to the old checkout experience which is being phased out.
+          xml.tag! 'HeaderBackColor', options[:header_background_color] unless options[:header_background_color].blank?
+          xml.tag! 'HeaderBorderColor', options[:header_border_color] unless options[:header_border_color].blank?
+          xml.tag! 'ExtData', 'Name' => 'ALLOWNOTE', 'Value' => options[:allow_note]
+        end
+      end
+
+      def build_response(success, message, response, options = {})
+        PayflowExpressResponse.new(success, message, response, options)
+      end
+    end
+  end
+end
+

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

@@ -0,0 +1,15 @@
+require 'active_merchant/billing/gateways/payflow_express'
+
+module ActiveMerchant #:nodoc:
+  module Billing #:nodoc:
+    class PayflowExpressUkGateway < PayflowExpressGateway
+      self.default_currency = 'GBP'
+      self.partner = 'PayPalUk'
+
+      self.supported_countries = ['GB']
+      self.homepage_url = 'https://www.paypal.com/uk/cgi-bin/webscr?cmd=_additional-payment-overview-outside'
+      self.display_name = 'PayPal Express Checkout (UK)'
+    end
+  end
+end
+

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

@@ -0,0 +1,21 @@
+require 'active_merchant/billing/gateways/payflow'
+require 'active_merchant/billing/gateways/payflow_express_uk'
+
+module ActiveMerchant #:nodoc:
+  module Billing #:nodoc:
+    class PayflowUkGateway < PayflowGateway
+      self.default_currency = 'GBP'
+      self.partner = 'PayPalUk'
+
+      def express
+        @express ||= PayflowExpressUkGateway.new(@options)
+      end
+
+      self.supported_cardtypes = [:visa, :master, :american_express, :discover, :solo, :switch]
+      self.supported_countries = ['GB']
+      self.homepage_url = 'https://www.paypal.com/uk/webapps/mpp/pro'
+      self.display_name = 'PayPal Payments Pro (UK)'
+    end
+  end
+end
+

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

@@ -0,0 +1,353 @@
+require 'rexml/document'
+
+module ActiveMerchant #:nodoc:
+  module Billing #:nodoc:
+
+    # In NZ DPS supports ANZ, Westpac, National Bank, ASB and BNZ.
+    # In Australia DPS supports ANZ, NAB, Westpac, CBA, St George and Bank of South Australia.
+    # The Maybank in Malaysia is supported and the Citibank for Singapore.
+    class PaymentExpressGateway < Gateway
+      self.default_currency = 'NZD'
+      # PS supports all major credit cards; Visa, Mastercard, Amex, Diners, BankCard & JCB.
+      # Various white label cards can be accepted as well; Farmers, AirNZCard and Elders etc.
+      # Please note that not all acquirers and Eftpos networks can support some of these card types.
+      # VISA, Mastercard, Diners Club and Farmers cards are supported
+      #
+      # However, regular accounts with DPS only support VISA and Mastercard
+      self.supported_cardtypes = [ :visa, :master, :american_express, :diners_club, :jcb ]
+
+      self.supported_countries = %w[ AU CA DE ES FR GB HK IE MY NL NZ SG US ZA ]
+
+      self.homepage_url = 'http://www.paymentexpress.com/'
+      self.display_name = 'PaymentExpress'
+
+      self.live_url = self.test_url = 'https://sec.paymentexpress.com/pxpost.aspx'
+
+      APPROVED = '1'
+
+      TRANSACTIONS = {
+        :purchase       => 'Purchase',
+        :credit         => 'Refund',
+        :authorization  => 'Auth',
+        :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 = {})
+        requires!(options, :login, :password)
+        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
+
+      # Transfer pre-authorized funds immediately
+      # See: http://www.paymentexpress.com/technical_resources/ecommerce_nonhosted/pxpost.html#Authcomplete
+      def capture(money, identification, options = {})
+        request = build_capture_or_credit_request(money, identification, options)
+        commit(:capture, request)
+      end
+
+      # Refund funds to the card holder
+      def refund(money, identification, options = {})
+        requires!(options, :description)
+
+        request = build_capture_or_credit_request(money, identification, options)
+        commit(:credit, request)
+      end
+
+      def credit(money, identification, options = {})
+        ActiveMerchant.deprecated CREDIT_DEPRECATION_MESSAGE
+        refund(money, identification, options)
+      end
+
+      # 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
+      #
+      # 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)
+          add_billing_token(result, payment_source)
+        else
+          add_credit_card(result, payment_source)
+        end
+
+        add_amount(result, money, options)
+        add_invoice(result, options)
+        add_address_verification_data(result, options)
+        add_optional_elements(result, options)
+        result
+      end
+
+      def build_capture_or_credit_request(money, identification, options)
+        result = new_transaction
+
+        add_amount(result, money, options)
+        add_invoice(result, options)
+        add_reference(result, identification)
+        add_optional_elements(result, options)
+        result
+      end
+
+      def build_token_request(credit_card, options)
+        result = new_transaction
+        add_credit_card(result, credit_card)
+        add_amount(result, 100, options) #need to make an auth request for $1
+        add_token_request(result, options)
+        add_optional_elements(result, options)
+        result
+      end
+
+      def add_credentials(xml)
+        xml.add_element("PostUsername").text = @options[:login]
+        xml.add_element("PostPassword").text = @options[:password]
+      end
+
+      def add_reference(xml, identification)
+        xml.add_element("DpsTxnRef").text = identification
+      end
+
+      def add_credit_card(xml, credit_card)
+        xml.add_element("CardHolderName").text = credit_card.name
+        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)
+        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
+      end
+
+      def add_amount(xml, money, options)
+        xml.add_element("Amount").text = amount(money)
+        xml.add_element("InputCurrency").text = options[:currency] || currency(money)
+      end
+
+      def add_transaction_type(xml, action)
+        xml.add_element("TxnType").text = TRANSACTIONS[action]
+      end
+
+      def add_invoice(xml, options)
+        xml.add_element("TxnId").text = options[:order_id].to_s.slice(0, 16) unless options[:order_id].blank?
+        xml.add_element("MerchantReference").text = options[:description].to_s.slice(0, 50) unless options[:description].blank?
+      end
+
+      def add_address_verification_data(xml, options)
+        address = options[:billing_address] || options[:address]
+        return if address.nil?
+
+        xml.add_element("EnableAvsData").text = 1
+        xml.add_element("AvsAction").text = 1
+
+        xml.add_element("AvsStreetAddress").text = address[:address1]
+        xml.add_element("AvsPostCode").text = address[:zip]
+      end
+
+      # The options hash may contain optional data which will be passed
+      # through the specialized optional fields at PaymentExpress
+      # as follows:
+      #
+      #     {
+      #       :client_type => :web, # Possible values are: :web, :ivr, :moto, :unattended, :internet, or :recurring
+      #       :txn_data1 => "String up to 255 characters",
+      #       :txn_data2 => "String up to 255 characters",
+      #       :txn_data3 => "String up to 255 characters"
+      #     }
+      #
+      # +:client_type+, while not documented for PxPost, will be sent as
+      # the +ClientType+ XML element as described in the documentation for
+      # the PaymentExpress WebService: http://www.paymentexpress.com/Technical_Resources/Ecommerce_NonHosted/WebService#clientType
+      # (PaymentExpress have confirmed that this value works the same in PxPost).
+      # The value sent for +:client_type+ will be normalized and sent
+      # as one of the explicit values allowed by PxPost:
+      #
+      #     :web        => "Web"
+      #     :ivr        => "IVR"
+      #     :moto       => "MOTO"
+      #     :unattended => "Unattended"
+      #     :internet   => "Internet"
+      #     :recurring  => "Recurring"
+      #
+      # If you set the +:client_type+ to any value not listed above,
+      # the ClientType element WILL NOT BE INCLUDED at all in the
+      # POST data.
+      #
+      # +:txn_data1+, +:txn_data2+, and +:txn_data3+ will be sent as
+      # +TxnData1+, +TxnData2+, and +TxnData3+, respectively, and are
+      # free form fields of the merchant's choosing, as documented here:
+      # http://www.paymentexpress.com/technical_resources/ecommerce_nonhosted/pxpost.html#txndata
+      #
+      # These optional elements are added to all transaction types:
+      # +purchase+, +authorize+, +capture+, +refund+, +store+
+      def add_optional_elements(xml, options)
+        if client_type = normalized_client_type(options[:client_type])
+          xml.add_element("ClientType").text = client_type
+        end
+
+        xml.add_element("TxnData1").text = options[:txn_data1].to_s.slice(0,255) unless options[:txn_data1].blank?
+        xml.add_element("TxnData2").text = options[:txn_data2].to_s.slice(0,255) unless options[:txn_data2].blank?
+        xml.add_element("TxnData3").text = options[:txn_data3].to_s.slice(0,255) unless options[:txn_data3].blank?
+      end
+
+      def new_transaction
+        REXML::Document.new.add_element("Txn")
+      end
+
+      # Take in the request and post it to DPS
+      def commit(action, request)
+        add_credentials(request)
+        add_transaction_type(request, action)
+
+        # Parse the XML response
+        response = parse( ssl_post(self.live_url, request.to_s) )
+
+        # Return a response
+        PaymentExpressResponse.new(response[:success] == APPROVED, message_from(response), response,
+          :test => response[:test_mode] == '1',
+          :authorization => authorization_from(action, response)
+        )
+      end
+
+      # Response XML documentation: http://www.paymentexpress.com/technical_resources/ecommerce_nonhosted/pxpost.html#XMLTxnOutput
+      def parse(xml_string)
+        response = {}
+
+        xml = REXML::Document.new(xml_string)
+
+        # Gather all root elements such as HelpText
+        xml.elements.each('Txn/*') do |element|
+          response[element.name.underscore.to_sym] = element.text unless element.name == 'Transaction'
+        end
+
+        # Gather all transaction elements and prefix with "account_"
+        # So we could access the MerchantResponseText by going
+        # response[account_merchant_response_text]
+        xml.elements.each('Txn/Transaction/*') do |element|
+          response[element.name.underscore.to_sym] = element.text
+        end
+
+        response
+      end
+
+      def message_from(response)
+        (response[:card_holder_help_text] || response[:response_text])
+      end
+
+      def authorization_from(action, response)
+        case action
+        when :validate
+          (response[:billing_id] || response[:dps_billing_id])
+        else
+          response[:dps_txn_ref]
+        end
+      end
+
+      def format_date(month, year)
+        "#{format(month, :two_digits)}#{format(year, :two_digits)}"
+      end
+
+      def normalized_client_type(client_type_from_options)
+        case client_type_from_options.to_s.downcase
+          when 'web'        then "Web"
+          when 'ivr'        then "IVR"
+          when 'moto'       then "MOTO"
+          when 'unattended' then "Unattended"
+          when 'internet'   then "Internet"
+          when 'recurring'  then "Recurring"
+          else nil
+        end
+      end
+    end
+
+    class PaymentExpressResponse < Response
+      # add a method to response so we can easily get the token
+      # for Validate transactions
+      def token
+        @params["billing_id"] || @params["dps_billing_id"]
+      end
+    end
+  end
+end