rack-payment 0.0.1

data/lib/rack-payment.rb

@@ -0,0 +1,11 @@
+$LOAD_PATH.unshift File.dirname(__FILE__)
+
+%w( active_merchant rack bigdecimal forwardable ostruct erb ).each {|lib| require lib }
+
+require 'rack-payment/payment'
+require 'rack-payment/request'
+require 'rack-payment/response'
+require 'rack-payment/credit_card'
+require 'rack-payment/billing_address'
+require 'rack-payment/helper'
+require 'rack-payment/methods'

data/lib/rack-payment/billing_address.rb

@@ -0,0 +1,30 @@
+module Rack     #:nodoc:
+  class Payment #:nodoc:
+
+    class BillingAddress
+      attr_accessor :name, :address1, :city, :state, :zip, :country
+
+      def [] key
+        send key
+      end
+
+      def update options
+        options.each {|key, value| send "#{key}=", value }
+      end
+
+      def partially_filled_out?
+        %w( name address1 city state zip country ).each do |field|
+          return true unless send(field).nil?
+        end
+
+        return false
+      end
+
+      # Aliases
+
+      def street()       address1              end
+      def street=(value) self.address1=(value) end
+    end
+
+  end
+end

data/lib/rack-payment/credit_card.rb

@@ -0,0 +1,73 @@
+module Rack     #:nodoc:
+  class Payment #:nodoc:
+
+    class CreditCard
+
+      REQUIRED = %w( first_name last_name type number month year verification_value )
+
+      attr_accessor :active_merchant_card
+
+      def initialize
+        @active_merchant_card ||= ActiveMerchant::Billing::CreditCard.new
+      end
+
+      def [] key
+        send key
+      end
+
+      def method_missing name, *args, &block
+        if active_merchant_card.respond_to?(name)
+          active_merchant_card.send(name, *args, &block)
+        else
+          super
+        end
+      end
+
+      def partially_filled_out?
+        %w( type number verification_value month year first_name last_name ).each do |field|
+          return true unless send(field).nil?
+        end
+
+        return false
+      end
+
+      def fully_filled_out?
+        # errors.empty?
+        raise "Not yet spec'd"
+      end
+
+      def update options
+        options.each {|key, value| send "#{key}=", value }
+      end
+
+      # Aliases
+
+      def cvv()       verification_value              end
+      def cvv=(value) self.verification_value=(value) end
+
+      def expiration_year()       year              end
+      def expiration_year=(value) self.year=(value) end
+
+      def expiration_month()       month              end
+      def expiration_month=(value) self.month=(value) end
+
+      def type
+        active_merchant_card.type
+      end
+
+      def full_name
+        [ first_name, last_name ].compact.join(' ')
+      end
+
+      def errors
+        REQUIRED.inject([]) do |errors, required_attribute_name|
+          value = send required_attribute_name
+          errors << "#{ required_attribute_name.titleize } is required" if value.nil? or value.empty?
+          errors
+        end
+      end
+
+    end
+
+  end
+end

data/lib/rack-payment/helper.rb

@@ -0,0 +1,221 @@
+module Rack     #:nodoc:
+  class Payment #:nodoc:
+
+    # When you include {Rack::Payment::Methods} into your application, you 
+    # get a {#payment} method/object which gives you an instance of {Rack::Payment::Helper}
+    #
+    # {Rack::Payment::Helper} is the main API for working with {Rack::Payment}.  You use it to:
+    # 
+    #  * Set the {#amount} you want to charge someone
+    #  * Spit out the HTML for a credit card / billing information {#form} into your own application
+    #  * Set the {#credit_card} and {#billing_address} to be used when processing the payment
+    #  * Get {#errors} if something didn't work
+    #  * Get the {#response} from your billing gateway after charging (or attempting to charge) someone
+    #  * Get the URL to the image for a {#paypal_express_button}
+    #
+    class Helper
+      extend Forwardable
+
+      def_delegators :response, :amount_paid, :success?,
+                                :raw_authorize_response, :raw_authorize_response=,
+                                :raw_capture_response,   :raw_capture_response=, 
+                                :raw_express_response,   :raw_express_response=
+
+      def_delegators :rack_payment, :gateway, :built_in_form_path, :logger, :logger=
+
+      attr_accessor :rack_payment, :amount, :credit_card, :billing_address, :errors, :use_express, :response
+
+      # @param [Rack::Payment]
+      def initialize rack_payment
+        @rack_payment = rack_payment
+      end
+
+      def cc
+        credit_card
+      end
+
+      def use_express
+        @use_express.nil? ? false : @use_express # default to false
+      end
+
+      def use_express?
+        self.use_express == true
+      end
+
+      def use_express!
+        self.use_express = true 
+      end
+
+      # helper for getting the src of the express checkout image
+      def paypal_express_button
+        'https://www.paypal.com/en_US/i/btn/btn_xpressCheckout.gif'
+      end
+
+      def errors
+        @errors ||= []
+      end
+
+      def credit_card
+        @credit_card ||= CreditCard.new
+      end
+
+      def billing_address
+        @billing_address ||= BillingAddress.new
+      end
+
+      def response
+        @response ||= Response.new
+      end
+
+      def amount= value
+        @amount = BigDecimal(value.to_s)
+      end
+
+      def amount_in_cents
+        (amount * 100).to_i if amount
+      end
+
+      def card_or_address_partially_filled_out?
+        credit_card.partially_filled_out? or billing_address.partially_filled_out?
+      end
+
+      # The same as {#purchase} but it raises an exception on error.
+      def purchase! options
+        if response = purchase(options)
+          true
+        else
+          raise "Purchase failed.  #{ errors.join(', ') }"
+        end
+      end
+
+      # Move these out into a module or something?
+
+      def log_purchase_start transaction_id, options
+        logger.debug { "[#{transaction_id}] #purchase(#{options.inspect}) for amount_in_cents: #{ amount_in_cents.inspect }" } if logger
+      end
+
+      def log_invalid_credit_card transaction_id
+        logger.warn { "[#{transaction_id}] invalid credit card: #{ errors.inspect }" } if logger
+      end
+
+      def log_authorize_successful transaction_id, options
+        logger.debug { "[#{transaction_id}] #authorize(#{amount_in_cents.inspect}, <CreditCard for #{ credit_card.full_name.inspect }>, :ip => #{ options[:ip].inspect }) was successful" } if logger
+      end
+
+      def log_authorize_unsuccessful transaction_id, options
+        logger.debug { "[#{transaction_id}] #authorize(#{amount_in_cents.inspect}, <CreditCard for #{ credit_card.full_name.inspect }>, :ip => #{ options[:ip].inspect }) was unsuccessful: #{ errors.inspect }" } if logger
+      end
+
+      def log_capture_successful transaction_id
+          logger.debug { "[#{transaction_id}] #capture(#{amount_in_cents}, #{raw_authorize_response.authorization.inspect}) was successful" } if logger
+      end
+
+      def log_capture_unsuccessful transaction_id
+          logger.debug { "[#{transaction_id}] #capture(#{amount_in_cents}, #{raw_authorize_response.authorization.inspect}) was unsuccessful: #{ errors.inspect }" } if logger
+      end
+
+      # Fires off a purchase!
+      #
+      # This resets #errors and #response
+      #
+      def purchase options
+        transaction_id = DateTime.now.strftime('%Y-%m-%d %H:%M:%S %L') # %L to include milliseconds
+        log_purchase_start(transaction_id, options)
+
+        raise "#amount_in_cents must be greater than 0" unless amount_in_cents.to_i > 0
+        raise ArgumentError, "The :ip option is required when calling #purchase" unless options and options[:ip]
+
+        # Check for Credit Card errors
+        self.response = Response.new
+        self.errors   = credit_card.errors # start off with any errors from the credit_card
+
+        # Try to #authorize (if no errors so far)
+        if errors.empty?
+          begin
+            # TODO should pass :billing_address, if the billing address isn't empty.
+            #      fields: name, address1, city, state, country, zip.
+            #      Some gateways (eg. PayPal Pro) require a billing_address!
+            self.raw_authorize_response = gateway.authorize amount_in_cents, credit_card.active_merchant_card, :ip => options[:ip]
+            unless raw_authorize_response.success?
+              errors << raw_authorize_response.message
+              log_authorize_unsuccessful(transaction_id, options)
+            end
+          rescue ActiveMerchant::Billing::Error => error
+            self.raw_authorize_response = OpenStruct.new :success? => false, :message => error.message, :authorization => nil
+            errors << error.message
+            log_authorize_unsuccessful(transaction_id, options)
+          end
+        else
+          log_invalid_credit_card(transaction_id)
+        end
+
+        # Try to #capture (if no errors so far)
+        if errors.empty?
+          log_authorize_successful(transaction_id, options)
+          begin
+            self.raw_capture_response = gateway.capture amount_in_cents, raw_authorize_response.authorization
+            unless raw_capture_response.success?
+              errors << raw_capture_response.message
+              log_capture_unsuccessful(transaction_id)
+            end
+          rescue ActiveMerchant::Billing::Error => error
+            self.raw_capture_response = OpenStruct.new :success? => false, :message => error.message
+            errors << raw_capture_response.message
+            log_capture_unsuccessful(transaction_id)
+          end
+        end
+
+        log_capture_successful(transaction_id) if errors.empty?
+
+        return errors.empty?
+      end
+
+      # Returns the HTML for the built in form
+      #
+      # By default, the form will POST to the current URL (action='')
+      #
+      # You can pass a different URL for the form action
+      def form post_to = ''
+        css  = ::File.dirname(__FILE__) + '/views/credit-card-and-billing-info-form.css'
+        view = ::File.dirname(__FILE__) + '/views/credit-card-and-billing-info-form.html.erb'
+        erb  = ::File.read view
+
+        html = "<style type='text/css'>\n#{ ::File.read(css) }\n</style>"
+        html << ERB.new(erb).result(binding)
+      end
+
+      def options_for_expiration_month selected = nil
+        %w( 01 02 03 04 05 06 07 08 09 10 11 12 ).map { |month|
+          if selected and selected.to_s == month.to_s
+            "<option selected='selected'>#{ month }</option>"
+          else
+            "<option>#{ month }</option>"
+          end
+        }.join
+      end
+
+      def options_for_expiration_year selected = nil
+        (Date.today.year..(Date.today.year + 15)).map { |year|
+          if selected and selected.to_s == year.to_s
+            "<option selected='selected'>#{ year }</option>"
+          else
+            "<option>#{ year }</option>"
+          end
+        }.join
+      end
+
+      def options_for_credit_card_type selected = nil
+        [ ['visa', 'Visa'], ['master', 'MasterCard'], ['american_express', 'American Express'], 
+          ['discover', 'Discover'] ].map { |value, name|
+        
+          if selected and selected.to_s == value.to_s
+            "<options value='#{ value }' selected='selected'>#{ name }</option>"
+          else
+            "<options value='#{ value }'>#{ name }</option>"
+          end
+        }.join
+      end
+    end
+
+  end
+end

data/lib/rack-payment/methods.rb

@@ -0,0 +1,52 @@
+module Rack     #:nodoc:
+  class Payment #:nodoc:
+
+    # This is intended to be included in your Rack/Sinatra/Rails application.
+    #
+    # It gives you a {#payment} object, which is the main API for working with {Rack::Payment}.
+    #
+    # It also gives you access to the instance of the {Rack::Payment} you included via {#rack_payment}
+    module Methods
+
+      # Returns an instance of {Rack::Payment::Helper}, which is the main API for working with {Rack::Payment}
+      #
+      # This assumes that this is available via env['rack.payment']
+      #
+      # If you override the {Rack::Payment#env_instance_variable}, you will need to 
+      # pass that string as an option to {#rack_payment}
+      def payment env_instance_variable = Rack::Payment::DEFAULT_OPTIONS['env_instance_variable']
+        rack_payment_instance = rack_payment(env_instance_variable)
+        _request_env[ rack_payment_instance.env_helper_variable ] ||= Rack::Payment::Helper.new(rack_payment_instance)
+      end
+
+      # Returns the instance of {Rack::Payment} your application is using.
+      #
+      # This assumes that this is available via env['rack.payment']
+      #
+      # If you override the {Rack::Payment#env_instance_variable}, you will need to 
+      # pass that string as an option to {#rack_payment}
+      def rack_payment env_instance_variable = Rack::Payment::DEFAULT_OPTIONS['env_instance_variable']
+        _request_env[env_instance_variable]
+      end
+
+      # This method returns the Rack 'env' for the current request.
+      #
+      # This looks for #env or #request.env by default.  If these don't return 
+      # something, then we raise an exception and you should override this method 
+      # so it returns the Rack env that we need.
+      #
+      # @private
+      def _request_env
+        if respond_to?(:env)
+          env
+        elsif respond_to?(:request) and request.respond_to?(:env)
+          request.env
+        else
+          raise "Couldn't find 'env' ... please override #_request_env"
+        end
+      end
+
+    end
+
+  end
+end

data/lib/rack-payment/payment.rb

@@ -0,0 +1,252 @@
+module Rack #:nodoc:
+
+  # Rack::Payment is a Rack middleware for adding simple payment to your applications.
+  #
+  #   use Rack::Payment, :gateway => 'paypal', :login => '...', :password => '...'
+  #
+  # Rack::Payment wraps {ActiveMerchant} so any gateway that {ActiveMerchant} supports 
+  # *should* be usable in Rack::Payment.
+  #
+  # When you `#call` this middleware, a new {Rack::Payment::Request} instance 
+  # gets created and it does the actual logic to figure out what to do.
+  #
+  class Payment
+
+    # Default file names that we used to look for yml configuration.
+    # You can change {Rack::Payment::yml_file_names} to override.
+    YML_FILE_NAMES = %w( .rack-payment.yml rack-payment.yml config/rack-payment.yml 
+                         ../config/rack-payment payment.yml ../payment.yml config/payment.yml )
+
+    class << self
+
+      # A string of file names that we use to look for options, 
+      # if options are not passes to the Rack::Payment constructor.
+      #
+      # @return [Array(String)]
+      attr_accessor :yml_file_names
+
+      # A standard logger.  Defaults to nil.  We assume that this has 
+      # methods like #info that accept a String or a block.
+      #
+      # If this is set, new instances of Rack::Payment will use this logger by default.
+      #
+      # @return [Logger]
+      attr_accessor :logger
+    end
+
+    @yml_file_names = YML_FILE_NAMES
+
+    # These are the default values that we use to set the Rack::Payment attributes.
+    #
+    # These can all be overriden by passing the attribute name and new value to 
+    # the Rack::Payment constructor:
+    #
+    #   use Rack::Payment, :on_success => '/my-custom-page'
+    #
+    DEFAULT_OPTIONS = {
+      'on_success'            => nil,
+      'built_in_form_path'    => '/rack.payment/process',
+      'express_ok_path'       => '/rack.payment/express.callback/ok',
+      'express_cancel_path'   => '/rack.payment/express.callback/cancel',
+      'env_instance_variable' => 'rack.payment',
+      'env_helper_variable'   => 'rack.payment.helper',
+      'session_variable'      => 'rack.payment',
+      'rack_session_variable' => 'rack.session'
+    }
+
+    # The {Rack} application that this middleware was instantiated with
+    # @return [#call]
+    attr_accessor :app
+
+    # A standard logger.  Defaults to nil.  We assume that this has 
+    # methods like #info that accept a String or a block
+    # @return [Logger]
+    attr_accessor :logger
+
+    def logger #:nodoc:
+      @logger ||= Rack::Payment.logger
+    end
+
+    # When a payment is successful, we redirect to this path, if set.
+    # If this is `nil`, we display our own confirmation page.
+    # @return [String, nil] (nil)
+    attr_accessor :on_success
+
+    # This is the path that the built-in form POSTs to when submitting 
+    # Credit Card data.  This is only used if you use the built_in_form.
+    # See {#use_built_in_form} to enable/disable using the default form
+    # @return [String]
+    attr_accessor :built_in_form_path
+
+    # TODO implement!  NOT IMPLEMENTED YET
+    attr_accessor :use_built_in_form
+
+    # This is the path that we have express gateways (Paypal Express) 
+    # redirect to, after a purchase has been made.
+    # @return [String]
+    attr_accessor :express_ok_path
+
+    # This is the path that we have express gateways (Paypal Express) 
+    # redirect to if the user cancels their purchase.
+    # @return [String]
+    attr_accessor :express_cancel_path
+
+    # The name of the Rack env variable to use to access the instance 
+    # of Rack::Payment that your application is using as middleware.
+    # @return [String]
+    attr_accessor :env_instance_variable
+
+    # The name of the Rack env variable to use to access data about 
+    # the purchase being made.  Getting this out of the Rack env 
+    # gives you a {Rack::Payment::Helper} object.
+    # @return [String]
+    attr_accessor :env_helper_variable
+
+    # The name of the variable we put into the Rack::Session 
+    # to store anything that {Rack::Payment} needs to keep track 
+    # of between requests, eg. the amount that the user is trying 
+    # to spend.
+    # @return [String]
+    attr_accessor :session_variable
+
+    # The name of the Rack env variable used for the Rack::Session, 
+    # eg. `rack.session` (the default for Rack::Session::Cookie)
+    # @return [String]
+    attr_accessor :rack_session_variable
+
+    # The name of a type of ActiveMerchant::Billing::Gateway that we 
+    # want to use, eg. 'paypal'.  We use this to get the actual 
+    # ActiveMerchant::Billing::Gateway class, eg. ActiveMerchant::Billing::Paypal
+    # @return [String]
+    attr_accessor :gateway_type
+
+    # The options that are passed to {Rack::Payment} when you include it as a 
+    # middleware, minus the options that {Rack::Payment} uses.
+    #
+    # For example, if you instantiate a {Rack::Payment} middleware with Paypal, 
+    # this will probably include :login, :password, and :signature
+    # @return [Hash]
+    attr_accessor :gateway_options
+
+    # Uses the #gateway_options to instantiate a [paypal] express gateway
+    #
+    # If your main gateway is a PaypayGateway, we'll make a PaypalExpressGateway
+    # If your main gateway is a BogusGateway, we'll make a BogusExpressGateway
+    #
+    # For any gateway, we'll try to make a *ExpressGateway
+    #
+    # This ONLY works for classes underneath ActiveMerchant::Billing
+    #
+    # @return [ActiveMerchant::Billing::Gateway]
+    attr_accessor :express_gateway
+
+    def express_gateway
+      @express_gateway ||= ActiveMerchant::Billing::Base.gateway(express_gateway_type).new(gateway_options)
+    end
+
+    # The name of the gateway to use for an express gateway.
+    #
+    # If our {#gateway} is a ActiveMerchant::Billing::PaypalGateway, 
+    # this will return `paypal_express`
+    #
+    # Uses the class of #gateway to determine.
+    #
+    # @return [String]
+    def express_gateway_type
+      gateway.class.to_s.split('::').last.sub(/(\w+)Gateway$/, '\1_express')
+    end
+
+    # The actual instance of ActiveMerchant::Billing::Gateway object to use.
+    # Uses the #gateway_type and #gateway_options to instantiate a gateway.
+    # @return [ActiveMerchant::Billing::Gateway]
+    attr_accessor :gateway
+
+    def gateway
+      unless @gateway
+        begin
+          @gateway = ActiveMerchant::Billing::Base.gateway(gateway_type.to_s).new(gateway_options)
+        rescue NameError
+          # do nothing, @gateway should be nil because the gateway_type was invalid
+        end
+      end
+      @gateway
+    end
+
+    # @overload initialize(rack_application)
+    #   Not yet implemented.  This will search for a YML file or ENV variable to set options.
+    #   @param [#call] The Rack application for this middleware
+    #
+    # @overload initialize(rack_application, options)
+    #   Accepts a Hash of options where the :gateway option is used as the {#gateway_type}
+    #   @param [#call] The Rack application for this middleware
+    #   @param [Hash] Options for the gateway and for Rack::Payment
+    #
+    def initialize rack_application = nil, options = nil
+      options ||= {}
+      options = look_for_options_in_a_yml_file.merge(options) unless options['yml_config'] == false or options[:yml_config] == false
+      raise ArgumentError, "You must pass options (or put them in a yml file)." if options.empty?
+
+      @app             = rack_application
+      @gateway_options = options             # <---- need to remove *our* options from the gateway options!
+      @gateway_type    = options['gateway'] || options[:gateway]
+
+      raise ArgumentError, 'You must pass a valid Rack application' unless @app.nil? or @app.respond_to?(:call)
+      raise ArgumentError, 'You must pass a valid Gateway'          unless @gateway_type and gateway.is_a?(ActiveMerchant::Billing::Gateway)
+
+      DEFAULT_OPTIONS.each do |name, value|
+        # set the default
+        send "#{name}=", value
+
+        # override the value from options, if passed
+        if @gateway_options[name.to_s] 
+          send "#{name.to_s}=", @gateway_options.delete(name.to_s)
+        elsif @gateway_options[name.to_s.to_sym] 
+          send "#{name.to_s.to_sym}=", @gateway_options.delete(name.to_s.to_sym)
+        end
+      end
+    end
+
+    # The main Rack #call method required by every Rack application / middleware.
+    # @param [Hash] The Rack Request environment variables
+    def call env
+      raise "Rack::Payment was not initialized with a Rack application and cannot be #call'd" unless @app
+      env[env_instance_variable] ||= self   # make this instance available
+      return Request.new(env, self).finish  # a Request object actually returns the response
+    end
+
+    # Looks for options in a yml file with a conventional name (using Rack::Payment.yml_file_names)
+    # Returns an empty Hash, if no options are found from a yml file.
+    # @return [Hash]
+    def look_for_options_in_a_yml_file
+      Rack::Payment.yml_file_names.each do |filename|
+        if ::File.file?(filename)
+          options = YAML.load_file(filename)
+
+          # if the YAML loaded something and it's a Hash
+          if options and options.is_a?(Hash)
+
+            # handle RACK_ENV / RAILS_ENV so you can put your test/development/etc in the same file
+            if ENV['RACK_ENV'] and options[ENV['RACK_ENV']].is_a?(Hash)
+              options = options[ENV['RACK_ENV']]
+            elsif ENV['RAILS_ENV'] and options[ENV['RAILS_ENV']].is_a?(Hash)
+              options = options[ENV['RAILS_ENV']]
+            end
+
+            return options
+          end
+        end
+      end
+
+      return {}
+    end
+
+    # Returns a new {Rack::Payment::Helper} instance which can be 
+    # used to fire off single payments (without needing to make 
+    # web requests).
+    # @return [Rack::Payment::Helper]
+    def payment
+      Rack::Payment::Helper.new(self)
+    end
+
+  end
+end

data/lib/rack-payment/request.rb

@@ -0,0 +1,228 @@
+module Rack     #:nodoc:
+  class Payment #:nodoc:
+
+    # When you call {Rack::Payment#call}, a new {Rack::Payment::Request} instance 
+    # gets created and it does the actual logic to figure out what to do.
+    #
+    # The {#finish} method "executes" this class (it figures out what to do).
+    #
+    class Request
+      extend Forwardable
+
+      def_delegators :payment_instance, :app, :gateway, :express_gateway, :on_success, :built_in_form_path, 
+                                        :env_instance_variable, :env_helper_variable, :session_variable,
+                                        :rack_session_variable, :express_ok_path, :express_cancel_path,
+                                        :built_in_form_path
+      
+      def_delegators :request, :params
+
+      def_delegators :payment, :errors, :credit_card, :billing_address
+
+      # TODO test these!!!
+      def express_ok_url
+        ::File.join request.url.sub(request.path_info, ''), express_ok_path
+      end
+      def express_cancel_url
+        ::File.join request.url.sub(request.path_info, ''), express_cancel_path
+      end
+
+      # @return [Hash] Raw Rack env Hash
+      attr_accessor :env
+
+      # An instance of Rack::Request that wraps our {#env}.
+      # It makes it much easier to access the params, path, method, etc.
+      # @return Rack::Request
+      attr_accessor :request
+
+      # Rack::Response that results from calling the actual Rack application.
+      # [Rack::Response]
+      attr_accessor :app_response
+
+      # Whether or not this request's POST came from our built in forms.
+      # 
+      #  * If true, we think the POST came from our form.
+      #  * If false, we think the POST came from a user's custom form.
+      #
+      # @return [true, false]
+      attr_accessor :post_came_from_the_built_in_forms
+
+      # The instance of {Rack::Payment} that this Request is for
+      # @return [Rack::Payment]
+      attr_accessor :payment_instance
+
+      def post_came_from_the_built_in_forms?
+        post_came_from_the_built_in_forms == true
+      end
+
+      def payment
+        env[env_helper_variable] ||= Rack::Payment::Helper.new(payment_instance)
+      end
+
+      def session
+        env[rack_session_variable][session_variable] ||= {}
+      end
+
+      def amount_in_session
+        session[:amount]
+      end
+
+      def amount_in_session= value
+        session[:amount] = value
+      end
+
+      # Instantiates a {Rack::Payment::Request} object which basically wraps a 
+      # single request and handles all of the logic to determine what to do.
+      #
+      # Calling {#finish} will return the actual Rack response
+      #
+      # @param [Hash] The Rack Request environment variables
+      # @param [Rack::Payment] The instance of Rack::Payment handling this request
+      def initialize env, payment_instance
+        @payment_instance = payment_instance
+
+        self.env          = env
+        self.request      = Rack::Request.new @env
+
+        raw_rack_response = app.call env
+        self.app_response = Rack::Response.new raw_rack_response[2], raw_rack_response[0], raw_rack_response[1]
+      end
+
+      # Generates and returns the final rack response.
+      #
+      # This "runs" the request.  It's the main logic in {Rack::Payment}!
+      #
+      # @return [Array] A Rack response, eg. `[200, {}, ["Hello World"]]`
+      def finish
+
+        # The application returned a 402 ('Payment Required')
+        if app_response.status == 402
+          self.amount_in_session = payment.amount
+          
+          return setup_express_purchase if payment.use_express?
+          
+          if payment.card_or_address_partially_filled_out?
+            return process_credit_card
+          else
+            return credit_card_and_billing_info_response
+          end
+
+        # The requested path matches our built-in form
+        elsif request.path_info == built_in_form_path
+          self.post_came_from_the_built_in_forms = true
+          return process_credit_card 
+
+        # The requested path matches our callback for express payments
+        elsif request.path_info == express_ok_path
+          return process_express_payment_callback
+        end
+
+        # If we haven't returned anything, there was no reason for the 
+        # middleware to handle this request so we return the real 
+        # application's response.
+        app_response.finish
+      end
+
+      # Gets parameters, attempts an #authorize call, attempts a #capture call, 
+      # and renders the results.
+      def process_credit_card
+        payment.amount ||= amount_in_session
+
+        # The params *should* be set on the payment data object, but we accept 
+        # POST requests too, so we check the POST variables for credit_card 
+        # or billing_address fields
+        #
+        # TODO deprecate this in favor of the more conventional credit_card[number] syntax?
+        #
+        params.each do |field, value|
+          if field =~ /^credit_card_(\w+)/
+            payment.credit_card.update $1 => value
+          elsif field =~ /billing_address_(\w+)/
+            payment.billing_address.update $1 => value
+          end 
+        end
+
+        # We also accept credit_card[number] style params, which Rack supports
+        if params['credit_card'] and params['credit_card'].respond_to?(:each)
+          payment.credit_card.update params['credit_card']
+        end
+        if params['billing_address'] and params['billing_address'].respond_to?(:each)
+          payment.billing_address.update params['billing_address']
+        end
+
+        # Purchase!
+        if payment.purchase(:ip => request.ip)
+          render_on_success
+        else
+          render_on_error payment.errors
+        end
+      end
+
+      def setup_express_purchase
+        # TODO we should get the callback URLs to use from the Rack::Purchase
+        #      and they should be overridable
+
+        # TODO go BOOM if the express gateway isn't set!
+      
+        # TODO catch exceptions
+
+        # TODO catch ! success?
+        response = express_gateway.setup_purchase payment.amount_in_cents, :ip                => request.ip, 
+                                                                           :return_url        => express_ok_url,
+                                                                           :cancel_return_url => express_cancel_url
+
+        [ 302, {'Location' => express_gateway.redirect_url_for(response.token)}, ['Redirecting to PayPal Express Checkout'] ]
+      end
+
+      def render_on_error errors
+        if post_came_from_the_built_in_forms?
+          # we POSTed from our form, so let's re-render our form
+          credit_card_and_billing_info_response
+        else
+          # pass along the errors to the application's custom page, which should be the current URL
+          # so we can actually just re-call the same env (should display the form) using a GET
+          payment.errors = errors
+          new_env = env.clone
+          new_env['REQUEST_METHOD'] = 'GET'
+          new_env['PATH_INFO'] = on_success if request.path_info == express_ok_path # if express, we render on_success
+          app.call(new_env)
+        end
+      end
+
+      def render_on_success
+        if on_success
+          # on_success is overriden ... we #call the main application using the on_success path
+          new_env = env.clone
+          new_env['PATH_INFO']      = on_success
+          new_env['REQUEST_METHOD'] = 'GET'
+          app.call new_env
+        else
+          # on_success has not been overriden ... let's just display out own info
+          [ 200, {}, ["Order successful.  You should have been charged #{ payment.amount }" ]]
+        end
+      end
+
+      def credit_card_and_billing_info_response
+        form_html = payment.form built_in_form_path
+        layout    = ::File.dirname(__FILE__) + '/views/layout.html'
+        html      = ::File.read(layout)
+        html      = html.sub 'CONTENT', form_html
+
+        [ 200, {'Content-Type' => 'text/html'}, html ]
+      end
+
+      def process_express_payment_callback
+        payment.amount ||= amount_in_session # gets lost because we're coming here directly from PayPal
+
+        details = express_gateway.details_for params['token']
+
+        payment.raw_express_response = express_gateway.purchase payment.amount_in_cents, :ip       => request.ip,
+                                                                                         :token    => params['token'],
+                                                                                         :payer_id => details.payer_id
+
+        render_on_success
+      end
+
+    end
+
+  end
+end

data/lib/rack-payment/response.rb

@@ -0,0 +1,55 @@
+module Rack     #:nodoc:
+  class Payment #:nodoc:
+
+    # Represents the response you get when you try to make a purchase 
+    # from ActiveMerchant
+    class Response
+
+      attr_accessor :raw_authorize_response
+      attr_accessor :raw_capture_response
+      attr_accessor :raw_express_response
+
+      alias auth    raw_authorize_response
+      alias capture raw_capture_response
+      alias express raw_express_response
+
+      def has_responses?
+        auth or capture or express
+      end
+
+      def express?
+        express != nil
+      end
+
+      def amount_paid
+        if success?
+          if express?
+            express_amound_paid
+          else
+            (raw_capture_response.params['paid_amount'].to_f / 100)
+          end
+        end
+      end
+
+      def express_amound_paid
+        if success?
+          raw_express_response.params['gross_amount'].to_f
+        end
+      end
+
+      def success?
+        if express?
+          express_success?
+        else
+          auth and auth.success? and capture and capture.success?
+        end
+      end
+
+      def express_success?
+        raw_express_response.success?
+      end
+
+    end
+
+  end
+end

data/lib/rack-payment/test.rb

@@ -0,0 +1,42 @@
+# Helpers for testing Rack::Payment
+
+require 'ostruct'
+
+module ActiveMerchant #:nodoc:
+  module Billing      #:nodoc:
+
+    # ...
+    class BogusExpressGateway < BogusGateway
+
+      # override default purchase
+      def purchase amount, options
+        raise "amount required"  if amount.nil?
+        raise "options required" if options.nil? or options.empty?
+
+        formatted_amount = sprintf '%.2f', (amount.to_f / 100.0)
+
+        yml = "--- !ruby/object:ActiveMerchant::Billing::PaypalExpressResponse \nauthorization: 4GN164705L1464005\navs_result: \n code: \n postal_match: \n street_match: \n message: \ncvv_result: \n code: \n message: \nfraud_review: false\nmessage: Success\nparams: \n payment_status: Completed\n tax_amount_currency_id: USD\n correlation_id: 820981d27a38f\n timestamp: \"2010-01-21T04:33:37Z\"\n pending_reason: none\n token: EC-9UM24360U0340274A\n transaction_id: 4GN164705L1464005\n fee_amount_currency_id: USD\n transaction_type: express-checkout\n build: \"1152253\"\n tax_amount: \"0.00\"\n version: \"52.0\"\n receipt_id: \n gross_amount_currency_id: USD\n parent_transaction_id: \n fee_amount: \"0.73\"\n exchange_rate: \n gross_amount: \"#{ formatted_amount }\"\n payment_date: \"2010-01-21T04:33:36Z\"\n ack: Success\n reason_code: none\n payment_type: instant\nsuccess: true\ntest: true\n"
+
+        YAML.load(yml)
+      end
+    
+      def setup_purchase amount, options
+        raise "amount required"  if amount.nil?
+        raise "options required" if options.nil? or options.empty?
+        OpenStruct.new :token => '123'
+      end
+
+      def redirect_url_for token
+        raise "token required" if token.nil?
+        'http://www.some-express-gateway-url/'
+      end
+
+      def details_for token
+        raise "token required" if token.nil?
+        OpenStruct.new :payer_id => '1'
+      end
+
+    end
+
+  end
+end

data/lib/rack/payment.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + '/../rack-payment'

data/lib/rack/payment/test.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + '/../../rack-payment/test'

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: rack-payment
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- remi
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-24 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: active_merchant
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Turn-key E-Commerce for Ruby web applications
+email: remi@remitaylor.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/rack-payment/credit_card.rb
+- lib/rack-payment/request.rb
+- lib/rack-payment/test.rb
+- lib/rack-payment/payment.rb
+- lib/rack-payment/response.rb
+- lib/rack-payment/helper.rb
+- lib/rack-payment/billing_address.rb
+- lib/rack-payment/methods.rb
+- lib/rack-payment.rb
+- lib/rack/payment.rb
+- lib/rack/payment/test.rb
+has_rdoc: true
+homepage: http://github.com/devfu/rack-payment
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Turn-key E-Commerce for Ruby web applications
+test_files: []
+