servicemerchant 0.1.0

data/recurring_billing/lib/am_extensions/paypal_extension.rb

@@ -0,0 +1,170 @@
+module ActiveMerchant #:nodoc:
+  module Billing #:nodoc:
+    class PaypalGateway < Gateway#:nodoc:
+
+      # this file was originally located in activemerchant-1.3.2/lib/active_merchant/billing/gateways
+      # MANUAL https://www.paypal.com/en_US/pdf/PP_APIReference.pdf
+      # See also:
+      #   http://jadedpixel.lighthouseapp.com/projects/11599/tickets/17-patch-creating-paypal-recurring-payments-profile-with-activemerchant
+
+      remove_const("RECURRING_ACTIONS") if defined? RECURRING_ACTIONS
+      RECURRING_ACTIONS = Set.new([:add, :modify, :cancel, :inquiry])
+
+      # :interval - cannot exceed 1 year
+      # :interval[:unit] = :week | :semimonth | :month | :year
+
+      def recurring(money, credit_card, options = {})
+        options[:name] = credit_card.name if options[:name].blank? && credit_card
+        request = build_recurring_request(options[:profile_id].nil? ? :add : :modify, money, options) do |xml|
+          add_credit_card(xml, credit_card, options[:billing_address], options) if credit_card
+        end
+        commit options[:profile_id].nil? ? 'CreateRecurringPaymentsProfile' : 'UpdateRecurringPaymentsProfile', request
+      end
+
+      def cancel_recurring(profile_id, options)
+        request = build_recurring_request(:cancel, nil, options.update( :profile_id => profile_id ))
+        commit 'ManageRecurringPaymentsProfileStatus', request
+      end
+
+      def inquiry_recurring(profile_id, options = {})
+        request = build_recurring_request(:inquiry, nil, options.update( :profile_id => profile_id ))
+        commit 'GetRecurringPaymentsProfileDetails', request
+      end
+
+      private
+
+      def build_recurring_request(action, money, options)
+        unless RECURRING_ACTIONS.include?(action)
+          raise StandardError, "Invalid Recurring Profile Action: #{action}"
+        end
+
+        xml = Builder::XmlMarkup.new :indent => 2
+
+        if action == :add
+          xml.tag! 'CreateRecurringPaymentsProfileReq', 'xmlns' => PAYPAL_NAMESPACE do
+            xml.tag! 'CreateRecurringPaymentsProfileRequest', 'xmlns:n2' => EBAY_NAMESPACE do
+              xml.tag! 'n2:Version', 50.0 # API_VERSION  # must be >= 50.0
+              xml.tag! 'n2:CreateRecurringPaymentsProfileRequestDetails' do
+
+                yield xml   # put card information : CreditCardDetails
+
+
+                xml.tag! 'n2:RecurringPaymentsProfileDetails' do
+                  xml.tag! 'n2:BillingStartDate', format_date(options[:starting_at])
+                  # SubscriberName (optional)
+                  # SubscriberShippingAddress (optional)
+                  # ProfileReference (optional) = The merchant’s own unique reference or invoice number.
+                end
+
+                xml.tag! 'n2:ScheduleDetails' do
+                  xml.tag! 'n2:Description', options[:description] # <= 127 single-byte alphanumeric characters!!!
+                    # This field must match the corresponding billing agreement description included in the SetExpressCheckout reques
+                  # ? MaxFailedPayments
+                  # ? AutoBillOutstandingAmount = NoAutoBill / AddToNextBilling
+
+                  xml.tag! 'n2:PaymentPeriod' do
+                    # if == :semimonth, then payed at 1 & 15 day of month
+                    xml.tag! 'n2:BillingFrequency', options[:interval][:length]
+                    xml.tag! 'n2:BillingPeriod', format_unit(options[:interval][:unit])
+                    xml.tag! 'n2:Amount', amount(money), 'currencyID' => options[:currency] || currency(money)
+                    # ShippingAmount (optional)
+                    # TaxAmount (optional)
+                    xml.tag! 'n2:TotalBillingCycles', options[:total_payments].to_s unless options[:total_payments].nil?
+                  end
+
+                  # WARNING: Activation not tested
+                  unless options[:activation].nil?
+                    xml.tag! 'n2:ActivationDetails' do
+                      xml.tag! 'n2:InitialAmount', amount(options[:activation][:amount]), 'currencyID' => options[:currency] || currency(options[:activation][:amount])
+                      xml.tag! 'n2:FailedInitAmountAction', options[:activation][:failed_action] unless options[:activation][:failed_action] # 'ContinueOnFailure/CancelOnFailure'
+                      xml.tag! 'n2:MaxFailedPayments', options[:activation][:max_failed_payments].to_s unless options[:activation][:max_failed_payments].nil?
+                    end
+                  end
+
+                  # WARNING: trial option not tested
+                  unless options[:trial].nil?
+                    xml.tag! 'n2:TrialPeriod' do
+                      frequency, period = get_pay_period(options[:trial][:periodicity])
+                      xml.tag! 'n2:BillingFrequency', frequency.to_s
+                      xml.tag! 'n2:BillingPeriod', period
+                      xml.tag! 'n2:Amount', amount(options[:trial][:amount]), 'currencyID' => options[:currency] || currency(options[:trial][:amount])
+                      xml.tag! 'n2:TotalBillingCycles', options[:trial][:total_payments].to_s
+                    end
+                  end
+
+                end
+              end
+            end
+          end
+
+        elsif action == :modify
+          xml.tag! 'UpdateRecurringPaymentsProfileReq', 'xmlns' => PAYPAL_NAMESPACE do
+            xml.tag! 'UpdateRecurringPaymentsProfileRequest', 'xmlns:n2' => EBAY_NAMESPACE do
+              xml.tag! 'n2:Version', 50.0 # API_VERSION  # must be >= 50.0
+              xml.tag! 'n2:UpdateRecurringPaymentsProfileRequestDetails' do
+
+                xml.tag! 'n2:ProfileID', options[:profile_id]
+                xml.tag! 'n2:Note', options[:note] unless options[:note].nil?
+                xml.tag! 'n2:Description', options[:description] unless options[:description].nil? # <= 127 single-byte alphanumeric characters!!!
+
+                # SubscriberName (optional)
+                # SubscriberShippingAddress (optional)
+                # ProfileReference (optional) = The merchant’s own unique reference or invoice number.
+                xml.tag! 'n2:AdditionalBillingCycles', options[:additional_payments].to_s unless options[:additional_payments].nil?
+                xml.tag! 'n2:Amount', amount(money), 'currencyID' => options[:currency] || currency(money) unless money.nil?
+                # ShippingAmount (optional)
+                # TaxAmount (optional)
+                # OutStandingBalance (optional)
+                  # The current past due or outstanding amount for this profile. You can only
+                  # decrease the outstanding amount—it cannot be increased.
+                # ? AutoBillOutstandingAmount (optional) = NoAutoBill / AddToNextBilling
+                # ? MaxFailedPayments (optional) = The number of failed payments allowed before the profile is automatically suspended.
+
+                yield xml   # put card information : CreditCardDetails
+                  # Only enter credit card details for recurring payments with direct payments.
+                  # Credit card billing address is optional, but if you update any of the address
+                  # fields, you must enter all of them. For example, if you want to update the
+                  # street address, you must specify all of the address fields listed in
+                  # CreditCardDetailsType, not just the field for the street address.
+              end
+            end
+          end
+
+         elsif action == :cancel
+          xml.tag! 'ManageRecurringPaymentsProfileStatusReq', 'xmlns' => PAYPAL_NAMESPACE do
+            xml.tag! 'ManageRecurringPaymentsProfileStatusRequest', 'xmlns:n2' => EBAY_NAMESPACE do
+              xml.tag! 'n2:Version', 50.0
+              xml.tag! 'n2:ManageRecurringPaymentsProfileStatusRequestDetails' do
+                xml.tag! 'n2:ProfileID', options[:profile_id]
+                xml.tag! 'n2:Action', 'Cancel'
+                xml.tag! 'n2:Note', options[:note] unless options[:note].nil?
+              end
+            end
+          end
+
+        elsif action == :inquiry
+          xml.tag! 'GetRecurringPaymentsProfileDetailsReq', 'xmlns' => PAYPAL_NAMESPACE do
+            xml.tag! 'GetRecurringPaymentsProfileDetailsRequest', 'xmlns:n2' => EBAY_NAMESPACE do
+              xml.tag! 'n2:Version', 50.0
+              xml.tag! 'ProfileID', options[:profile_id]
+            end
+          end
+        end
+      end
+
+      def format_date(dat)
+        case dat.class.to_s
+          when 'Date' then return dat.strftime('%FT%T')
+          when 'Time' then return dat.getgm.strftime('%FT%T')
+          when 'String' then return dat
+        end
+      end
+
+      def format_unit(unit)
+        requires!({:data => unit}, [:data, 'Week', 'SemiMonth', 'Month', 'Year'])
+        unit.to_s.downcase.capitalize
+      end
+
+    end
+  end
+end

data/recurring_billing/lib/dependencies.rb

@@ -0,0 +1,14 @@
+require 'rubygems'
+
+gem 'activemerchant'
+require 'active_merchant'
+
+#TODO: Autodiscover new libs from vendor and add them to load path
+$: << File.dirname(__FILE__) + "/../../vendor/money-1.7.1/lib"
+require "money"
+
+gem 'activesupport'
+require 'active_support/core_ext/string/inflections'
+class String # :nodoc:
+  include ActiveSupport::CoreExtensions::String::Inflections
+end

data/recurring_billing/lib/gateways.rb

@@ -0,0 +1,5 @@
+require File.dirname(__FILE__) + '/utils'
+require File.dirname(__FILE__) + '/recurring_billing'
+require File.dirname(__FILE__) + '/am_extensions'
+
+Dir[File.dirname(__FILE__) + '/gateways/*.rb'].each{|g| require g}

data/recurring_billing/lib/gateways/authorize_net.rb

@@ -0,0 +1,103 @@
+module RecurringBilling
+  class AuthorizeNetGateway < RecurringBillingGateway
+    include Utils
+
+    def code
+      :authorize_net
+    end
+
+    def name
+      'Authorize.net'
+    end
+
+    # Check if update is possible using specified arguments
+    def correct_update?(billing_id, amount, card, payment_options, recurring_options)
+      if !recurring_options.nil? && recurring_options.length > 0
+        raise StandardError, 'Cannot update recurring options at #{name} gateway'
+      end
+      return true
+    end
+
+    # Make an update using gateway-specific actions
+    def update_specific(billing_id, amount, card, payment_options, recurring_options)
+      options = compile_options(amount, card, payment_options, recurring_options)
+      options[:amount] = amount
+      options[:subscription_id] = billing_id
+      (@last_response = @gateway.update_recurring(options)).success?
+    end
+
+    # Create payment using gateway-specific actions
+    def create_specific(amount, card, payment_options, recurring_options)
+      @last_response = @gateway.recurring(amount, card, compile_options(amount, card, payment_options, recurring_options))
+      return @last_response.authorization if @last_response.success?
+      nil
+    end
+
+    # Cancel the subscription
+    def delete_specific(billing_id)
+      (@last_response = @gateway.cancel_recurring(billing_id)).success?
+    end
+
+    # Get ready-to-send options hash
+    def compile_options(amount, card, payment_options, recurring_options)
+      new_options = {}
+      if !recurring_options.nil? && !recurring_options.empty?
+        requires!(recurring_options, :start_date, :interval)
+        requires!(recurring_options, :occurrences) unless recurring_options.has_key?(:end_date)
+        requires!(recurring_options, :end_date) unless recurring_options.has_key?(:occurrences)
+        transformed_dates = (recurring_options[:occurrences]) ?
+                             transform_dates(recurring_options[:start_date], recurring_options[:interval], recurring_options[:occurrences], nil) :
+                             transform_dates(recurring_options[:start_date], recurring_options[:interval], nil, recurring_options[:end_date])
+
+        new_options = {:interval => transformed_dates[:interval], :duration => transformed_dates[:duration]}
+      end
+
+      billing_address = payment_options.has_key?(:billing_address) ? payment_options[:billing_address] : {}
+      if (!billing_address.has_key?(:last_name) || billing_address[:last_name].empty?) && card
+        billing_address[:last_name] = card.last_name
+        billing_address[:first_name] = card.first_name
+      end
+
+
+      new_options[:billing_address] = billing_address
+      new_options[:subscription_name] = payment_options[:subscription_name] if payment_options.has_key?(:subscription_name)
+      new_options[:order] = payment_options[:order] if payment_options.has_key?(:order)
+
+      return new_options
+
+    end
+
+    #Transform dates to Authorize.net-recognizable format
+    def transform_dates(start_date, interval, occurrences, end_date)
+
+      raise ArgumentError, 'Either number of occurences OR end date should be specified' if (!occurrences.nil? && !end_date.nil?) || ((occurrences.nil? && end_date.nil?))
+      raise ArgumentError, 'Payment cycle start date ({#start_date}) should be less than or equal to end date ({#end_date})' if !end_date.nil? && (start_date>end_date)
+      raise ArgumentError, 'Number of payment occurrences should be a positive integer)' if !occurrences.nil? && (occurrences <= 0)
+
+      i_length, i_unit = parse_interval(interval)
+
+      if i_length == 0.5 && (i_unit != :y)
+        raise ArgumentError, "Semi- interval is not supported to this units (#{i_unit.to_s})"
+      end
+
+      new_interval =  case i_unit
+                        when :d then {:length=>i_length,    :unit=>:days}
+                        when :w then {:length=>i_length*7,  :unit=>:days}
+                        when :m then {:length=>i_length,    :unit=>:months}
+                        when :y then {:length=>i_length*12, :unit=>:months}
+                      end
+      if !occurrences.nil?
+        return {:interval=>new_interval, :duration=>{:start_date=>start_date, :occurrences=>occurrences}}
+      else
+        if new_interval[:unit] == :days
+          new_occurrences = 1 + ((end_date - start_date)/new_interval[:length]).to_i
+        elsif new_interval[:unit] == :months
+          new_occurrences = 1 + (months_between(end_date, start_date)/new_interval[:length]).to_i
+        end
+        return {:interval=>new_interval, :duration=>{:start_date=>start_date, :occurrences=>new_occurrences}}
+      end
+    end
+
+
+  end
+end

data/recurring_billing/lib/gateways/paypal.rb

@@ -0,0 +1,124 @@
+module RecurringBilling
+  class PaypalGateway < RecurringBillingGateway
+    include Utils
+    
+    # Returns :paypal
+    def code
+      :paypal
+    end
+
+    # Returns 'PayPal Website Payments Pro (US)'
+    def name
+      'PayPal Website Payments Pro (US)'
+    end
+
+    # Checks whether passed parameters of requested recurring payment conform to specification
+    def correct_create?(amount, card, payment_options, recurring_options)
+      raise ArgumentError, 'Ammount must be defined and more than zero' if amount.nil? || amount.zero?
+      raise ArgumentError, 'Card is mandatory' if card.nil? # must be object of CreditCard class
+      raise ArgumentError, 'Subscription name is mandatory' if payment_options[:subscription_name].to_s.empty?
+      raise ArgumentError, 'Starting date is mandatory' if recurring_options[:start_date].to_s.empty?
+      raise ArgumentError, 'Interval is mandatory' if recurring_options[:interval].to_s.empty?
+      # end_date and occurrences - both can be ommited
+      return true
+    end
+
+
+    # Checks if update is possible using specified arguments
+    def correct_update?(billing_id, amount, card, payment_options, recurring_options)
+      raise ArgumentError, 'Billing ID is mandatory' if billing_id.to_s.empty?
+      raise ArgumentError, 'Starting date cannot be updated' if !recurring_options[:start_date].to_s.empty?
+      raise ArgumentError, 'Interval cannot be updated' if !recurring_options[:interval].to_s.empty?
+
+      if !(recurring_options[:end_date].to_s.empty? && recurring_options[:occurrences].to_s.empty?)
+        raise NotImplementedError, 'Cannot shift the end of recurring payment'
+        # it is made via "AdditionalBillingCycles", so we have to know previous data
+      end
+      return true
+    end
+
+    # Create payment using gateway-specific actions
+    def create_specific(amount, card, payment_options, recurring_options)
+      @last_response = @gateway.recurring(amount, card, convert_options(payment_options, recurring_options))
+      return @last_response.params['profile_id'] if @last_response.success?
+      nil
+    end
+
+    # Make an update using gateway-specific actions
+    def update_specific(billing_id, amount, card, payment_options, recurring_options)
+      options = convert_options(payment_options, recurring_options)
+      options[:profile_id] = billing_id
+      (@last_response = @gateway.recurring(amount, card, options)).success?
+    end
+
+    # Cancel the subscription
+    # TODO: Add :note parameter to API to enable it in update and cancel
+    def delete_specific(billing_id)
+      (@last_response = @gateway.cancel_recurring(billing_id, {})).success?
+    end
+
+    # TODO: Unify result parameters names and values
+    def inquiry_specific(billing_id)
+      @last_response = @gateway.inquiry_recurring(billing_id)
+      result = @last_response.params.clone
+
+      result.each do |k,v|
+        if k =~ /(^number_|_count$|_cycles(_|$)|_payments$|_frequency$|_month$|_year$)/
+          result[k] = v.to_i
+        elsif k =~ /(_date|^timestamp)$/
+          result[k] = DateTime.parse(v)
+        elsif (k =~ /(_|^)amount(_paid)?$/ && k != 'auto_bill_outstanding_amount') || k =~ /_balance$/
+          currency = result[k+'_currency_id']
+          result[k] = Money.new(v.to_f*100, currency=currency) # dollars => cents
+        elsif k =~ /_(status|period|card_type)$/
+          result[k] = v.downcase
+        end
+      end
+
+      result['profile_status'] =~ /^(.*)Profile$/i
+      result['profile_status'] = $1 # active | pending | cancelled | suspended | expired
+
+      return result.reject {|k,v| k =~ /_currency_id$/}
+    end
+
+
+    def convert_options(payment_options, recurring_options)
+      options = {}
+      options[:billing_address] = payment_options[:billing_address] if !payment_options[:billing_address].nil?
+      options[:description] = payment_options[:subscription_name]
+      options[:starting_at] = recurring_options[:start_date]
+      options[:total_payments] = recurring_options[:occurrences] if !recurring_options[:occurrences].nil?
+      options[:interval] = convert_interval(recurring_options[:interval]) if !recurring_options[:interval].nil? # absent for update
+      options[:currency] = payment_options[:currency] if !payment_options[:currency].nil?
+      #options[:note] = payment_options[:note] if !payment_options[:note].nil?
+      return options
+    end
+
+
+    def convert_interval(interval)
+      i_length, i_unit = parse_interval(interval)
+
+      if i_length == 0.5 && ![:m,:y].include?(i_unit)
+        raise ArgumentError, "Semi- interval is not supported to this units (#{i_unit.to_s})"
+      end
+
+      if    [i_length, i_unit] == [0.5, :m]
+        return {:length => 1, :unit => 'SemiMonth'}
+      elsif [i_length, i_unit] == [0.5, :y]
+        i_length, i_unit = [6, :m]
+      end
+
+      return {:length => i_length, :unit => convert_unit(i_unit)}
+    end
+
+    def convert_unit(unit)
+      return  case unit
+                when :d then 'Day'
+                when :w then 'Week'
+                when :m then 'Month'
+                when :y then 'Year'
+              end
+    end
+
+  end
+end

data/recurring_billing/lib/recurring_billing.rb

@@ -0,0 +1,130 @@
+require File.dirname(__FILE__) + '/dependencies'
+
+# RecurringBilling module provides common API for managing recurring billing operations
+# via remote gateway. All manipulations are done through instances of RecurringBillingGateway
+# and its descendants (though direct use of that class descendants is discouraged).
+#
+# Please see RecurringBillingGateway for more detailed reference.
+module RecurringBilling
+
+  #:include:recurring_billing.rdoc
+  #:include:recurring_billing_extension.rdoc
+  class RecurringBillingGateway
+    include ActiveMerchant::RequiresParameters
+    attr_reader :last_response
+
+    # Returns code that is used to identify the gateway
+    def code
+      raise NotImplementedError, 'Method is virtual'
+    end
+
+    # Returns gateway name
+    def name
+      raise NotImplementedError, 'Method is virtual'
+    end
+
+    # Creates a new recurring billing gateway
+    def initialize(options)#:nodoc:
+      @gateway =     ::ActiveMerchant::Billing::Base.gateway(code).new(
+        :login      => options[:login],
+        :password   => options[:password],
+        :test       => options[:is_test].nil? ? false : options[:is_test], # false by default
+        :signature  => options[:signature]
+        )
+      @last_response = nil
+    end
+
+    # Creates a recurring payment
+    def create(amount, card, payment_options={}, recurring_options={})
+      if correct_create?(amount, card, payment_options, recurring_options)
+        create_specific(amount, card, payment_options, recurring_options)
+      end
+    end
+
+    # Updates a recurring payment
+    def update(billing_id, amount=nil, card=nil, payment_options={}, recurring_options={})
+      if correct_update?(billing_id, amount, card, payment_options, recurring_options)
+        update_specific(billing_id, amount, card, payment_options, recurring_options)
+      end
+    end
+
+    # Deletes a recurring payment
+    def delete(billing_id)
+      delete_specific(billing_id)
+    end
+
+    # Asks for status of recurring payment
+    def inquiry(billing_id)
+      inquiry_specific(billing_id)
+    end
+
+    class << self
+      # Converts single options hash into hash of parameters used by create|update methods
+      #
+      # :amount or :billing_amount => amount
+      # :card => card
+      # :subscription_name, :billing_address, :order, :taxes_amount_included => payment_options
+      # :start_date, :interval, :end_date, :trial_end, :occurrences, :trial_occurrences => recurring_options
+      def separate_create_update_params_from_options(options)
+        payment_options, recurring_options = {}, {}
+        amount = options[:billing_amount] unless amount = options[:amount]
+        card = options[:card]
+        options.each do |k,v|
+          payment_options[k] = v if [:subscription_name, :billing_address, :order, :taxes_amount_included].include?(k)
+          recurring_options[k] = v if [:start_date, :interval, :end_date, :trial_end, :occurrences, :trial_occurrences, :trial_days, :pay_on_day_x].include?(k)
+        end
+
+        return {:amount => amount, :card => card, :payment_options => payment_options, :recurring_options => recurring_options}
+      end
+
+
+      # Returns an instance of RecurringBillingGateway for selected gateway
+      #
+      # options <= hash of :gateway, :login, :password, :is_test(optional), :signature(optional)
+      def get_instance(options)
+        raise ArgumentError, ':gateway key is required' unless options.has_key?(:gateway)
+
+        gateway = RecurringBilling.const_get("#{options[:gateway].to_s.downcase}_gateway".camelize)
+        gateway.new(options)
+      end
+    end
+
+    ###
+    protected
+    # Checks whether requested change can be done via simple update (or recreate needed)
+    def correct_update?(billing_id, amount, card, payment_options, recurring_options)
+      raise NotImplementedError, 'Method is virtual'
+    end
+
+    # Make an update using gateway-specific actions
+    def update_specific(billing_id, amount, card, payment_options, recurring_options)
+      raise NotImplementedError, 'Method is virtual'
+    end
+    # Checks whether passed parameters of requested recurring payment conform to specification
+    def correct_create?(amount, card, payment_options, recurring_options)
+        raise ArgumentError, 'Card must be of ActiveMerchant::Billing::CreditCard' unless card.is_a?(ActiveMerchant::Billing::CreditCard)
+      if (!recurring_options) || !(recurring_options.has_key?(:end_date) || recurring_options.has_key?(:occurrences))
+        raise StandardError, 'Either payments'' end date or number of payment occurences should be set'
+      end
+      return true
+    end
+
+    # Creates a recurring payment using gateway-specific actions (virtual)
+    def create_specific(amount, card, payment_options, recurring_options)
+      raise NotImplementedError, 'Method is virtual'
+    end
+
+    # Deletes a recurring payment
+    def delete_specific(billing_id)
+      raise NotImplementedError, 'Method is virtual'
+    end
+
+    # Inquires status of given subscription profile on payment gateway.
+    def inquiry_specific(billing_id)
+      raise NotImplementedError, 'Method is virtual'
+    end
+
+  end
+end
+
+require File.dirname(__FILE__) + "/gateways"