activemerchant 1.2.1 → 1.3.0

data/CONTRIBUTERS

@@ -46,7 +46,20 @@ Viaklix Gateway (Sep 3, 2007)
 Braintree Gateway (Sep 4, 2007)
 
 * Originally contributed by Michael J. Mangino
+* Portions of the BrainTree gateway by Jeremy Voorhis
 
 Concord Efsnet Gateway (Sep 7, 2007)
 
 * Originally contributed by snacktime
+
+SecurePayTech Gateway (Oct 23, 2007)
+
+* Originally contributed by Jasper Bryant-Greene
+
+SkipJack Gateway (Nov 29, 2007)
+
+* Originally contributed by Bill Bereza - http://atomicobject.com
+
+HiTRUST Gateway (Dec 10, 2007)
+
+* Jaded Pixel

data/README

@@ -1,14 +1,16 @@
 = Active Merchant
 
-This library is supposed to aid in creating e-commerce software in Ruby. 
-In the future we want to support all "good" payment gateways. 
+This library is supposed to aid in creating e-commerce software in Ruby.
+In the future we want to support all "good" payment gateways.
 
-This library is the foundation of commerce for http://www.shopify.com. 
+This library is the foundation of commerce for http://www.shopify.com.
 
-Please visit the {ActiveMerchant homepage}[http://activemerchant.org] for more resources, tutorials and other information about this project. 
+Please visit the {ActiveMerchant homepage}[http://activemerchant.org] for more resources, tutorials and other information about this project.
 
 == Supported Direct Payment Gateways
 
+The {ActiveMerchant Wiki}[http://code.google.com/p/activemerchant/wiki] contains a {table of features supported by each gateway}[http://code.google.com/p/activemerchant/wiki/SupportedGatewayPaymentOperations].
+
 * {Authorize.net}[http://www.authorize.net/] - US
 * {Braintree}[http://www.braintreepaymentsolutions.com] - US
 * {CardStream}[http://www.cardstream.com/] - GB
@@ -20,7 +22,9 @@ Please visit the {ActiveMerchant homepage}[http://activemerchant.org] for more r
 * {LinkPoint}[http://www.linkpoint.com/] - US
 * {Moneris}[http://www.moneris.com/] - CA
 * {NetRegistry}[http://www.netregistry.com.au] - AU
+* {NETbilling}[http://www.netbilling.com] - US
 * {PayJunction}[http://www.payjunction.com/] - US
+* {PaySecure}[http://www.commsecure.com.au/paysecure.shtml] - AU
 * {PayPal Express Checkout}[https://www.paypal.com/cgi-bin/webscr?cmd=xpt/merchant/ExpressCheckoutIntro-outside] - US, CA, SG, AU
 * {PayPal Express Checkout (UK)}[https://www.paypal.com/uk/cgi-bin/webscr?cmd=_additional-payment-overview-outside] - GB
 * {PayPal Payflow Pro}[https://www.paypal.com/cgi-bin/webscr?cmd=_payflow-pro-overview-outside] - US, CA, SG, AU
@@ -35,26 +39,29 @@ Please visit the {ActiveMerchant homepage}[http://activemerchant.org] for more r
 * {Quickpay}[http://quickpay.dk/] - DK
 * {Realex}[http://www.realexpayments.com/] - IE, GB
 * {SecurePay}[http://www.securepay.com/] - US
+* {SecurePayTech}[http://www.securepaytech.com/] - NZ
+* {SkipJack}[http://www.skipjack.com/] - US, CA
 * {TransFirst}[http://www.transfirst.com/] - US
 * {TrustCommerce}[http://www.trustcommerce.com/] - US
-* {USA ePay}[http://www.usa_epay.com/] - US
+* {USA ePay}[http://www.usaepay.com/] - US
 * {Verifi}[http://www.verifi.com/] - US
 * {ViaKLIX}[http://viaklix.com] - US
 
 == Supported Offsite Payment Gateways
- 
+
 * {PayPal Website Payments Standard}[https://www.paypal.com/cgi-bin/webscr?cmd=_wp-standard-overview-outside]
 * Chronopay[http://www.chronopay.com]
 * Nochex[http://www.nochex.com]
 * {Banca Sella GestPay}[https://www.sella.it/banca/ecommerce/gestpay/gestpay.jsp]
 * {2 Checkout}[http://www.2checkout.com]
- 
+* {HiTRUST}[http://www.hitrust.com.hk/]
+
 == Download
 
 Currently this library is available with svn from:
 
-	http://activemerchant.googlecode.com/svn/trunk/active_merchant
-	
+  http://activemerchant.googlecode.com/svn/trunk/active_merchant
+
 == Installation
 
 === From Subversion
@@ -73,31 +80,48 @@ ActiveMerchant includes an init.rb file. This means that Rails will automaticall
 
 Installation from RubyGems
 
-  > gem install activemerchant -y
+  > gem install activemerchant
 
 == Sample Usage
+  require 'rubygems'
+  require 'active_merchant'
+
+  # Use the TrustCommerce test servers
+  ActiveMerchant::Billing::Base.mode = :test
+
+  # ActiveMerchant accepts all amounts as Integer values in cents
+  # $10.00
+  amount = 1000
+
+  # The card verification value is also known as CVV2, CVC2, or CID 
+  credit_card = ActiveMerchant::Billing::CreditCard.new(
+                  :first_name         => 'Bob',
+                  :last_name          => 'Bobsen',
+                  :number             => '4242424242424242',
+                  :month              => '8',
+                  :year               => '2012',
+                  :verification_value => '123'
+                )
+
+  # Validating the card automatically detects the card type
+  if credit_card.valid?
+
+    # Create a gateway object for the TrustCommerce service
+    gateway = ActiveMerchant::Billing::TrustCommerceGateway.new(
+                :login => 'TestMerchant',
+                :password => 'password'
+              )
+
+    # Authorize for the amount
+    response = gateway.purchase(amount, credit_card)
 
-  # 10 dollars in cents
-  ten_dollars = 1000
-
-  credit_card = CreditCard.new(
-    :number => '4242424242424242',
-    :month => 8,
-    :year => 2006,
-    :name => 'Tobias Luetke',
-    :type => 'visa'
-  )
-
-  if creditcard.valid?
-    gateway = ActiveMerchant::Billing::AuthorizeNetGateway.new(
-      :login    => 'LOGIN_ID',
-      :password => 'TRANSACTION_KEY'
-    )
-    response = gateway.purchase(ten_dollars, credit_card)
-    
     if response.success?
-      ...
+      puts "Successfully charged $#{sprintf("%.2f", amount / 100)} to the credit card #{credit_card.display_number}"
     else
-      raise StandardError.new( response.message )
+      raise StandardError, response.message 
     end
-  end
+  end
+
+== Contributing
+
+Please see the {ActiveMerchant Guide to Contributing}[http://code.google.com/p/activemerchant/wiki/Contributing] for information on adding a new gateway to ActiveMerchant.

data/Rakefile

@@ -8,7 +8,7 @@ require File.dirname(__FILE__) + '/lib/tasks/cia'
 require File.dirname(__FILE__) + '/lib/support/gateway_support'
 
 
-PKG_VERSION = "1.2.1"
+PKG_VERSION = "1.3.0"
 PKG_NAME = "activemerchant"
 PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
 
@@ -30,7 +30,7 @@ namespace :test do
   end
 
   Rake::TestTask.new(:remote) do |t|
-    t.pattern = 'test/remote_tests/*_test.rb'
+    t.pattern = 'test/remote/**/*_test.rb'
     t.ruby_opts << '-rubygems'
     t.verbose = true
   end
@@ -129,22 +129,30 @@ task :upload_rdoc => :rdoc do
 end
 
 namespace :gateways do
-  desc 'Print the currently supported gateways in RDoc format'
-  task :print_support_rdoc do
-    support = GatewaySupport.new
-    support.to_rdoc
-  end
-  
   desc 'Print the currently supported gateways'
-  task :print_support do
+  task :print do
     support = GatewaySupport.new
     support.to_s
   end
   
-  desc 'Print the currently supported gateways'
-  task :print_support_textile do
-    support = GatewaySupport.new
-    support.to_textile
+  namespace :print do
+    desc 'Print the currently supported gateways in RDoc format'
+    task :rdoc do
+      support = GatewaySupport.new
+      support.to_rdoc
+    end
+  
+    desc 'Print the currently supported gateways in Textile format'
+    task :textile do
+      support = GatewaySupport.new
+      support.to_textile
+    end
+    
+    desc 'Print the gateway functionality supported by each gateway'
+    task :features do
+      support = GatewaySupport.new
+      support.features
+    end
   end
 end
   

data/lib/active_merchant.rb

@@ -40,6 +40,7 @@ end
 
 require 'cgi'
 
+require 'active_merchant/lib/utils'
 require 'active_merchant/lib/error'
 require 'active_merchant/lib/validateable'
 require 'active_merchant/lib/posts_data'
@@ -49,6 +50,12 @@ require 'active_merchant/lib/requires_parameters'
 # Require the country class
 require 'active_merchant/lib/country'
 
+# Address Verification
+require 'active_merchant/billing/avs_result'
+
+# Card Verfication Code
+require 'active_merchant/billing/cvv_result'
+
 # CreditCard Utility class. 
 require 'active_merchant/billing/credit_card_methods'
 require 'active_merchant/billing/credit_card_formatting'

data/lib/active_merchant/billing/avs_result.rb

@@ -0,0 +1,95 @@
+module ActiveMerchant
+  module Billing 
+    # Implements the Address Verification System
+    # https://www.wellsfargo.com/downloads/pdf/biz/merchant/visa_avs.pdf
+    # http://en.wikipedia.org/wiki/Address_Verification_System
+    # http://apps.cybersource.com/library/documentation/dev_guides/CC_Svcs_IG/html/app_avs_cvn_codes.htm#app_AVS_CVN_codes_7891_48375
+    # http://imgserver.skipjack.com/imgServer/5293710/AVS%20and%20CVV2.pdf
+    # http://www.emsecommerce.net/avs_cvv2_response_codes.htm
+    class AVSResult
+      MESSAGES = {
+        'A' => 'Street address matches, but 5-digit and 9-digit postal code do not match.',
+        'B' => 'Street address matches, but postal code not verified.',
+        'C' => 'Street address and postal code do not match.',
+        'D' => 'Street address and postal code match.',
+        'E' => 'AVS data is invalid or AVS is not allowed for this card type.',
+        'F' => 'Card member’s name does not match, but billing postal code matches.',
+        'G' => 'Non-U.S. issuing bank does not support AVS.',
+        'H' => 'Card member’s name does not match. Street address and postal code match.',
+        'I' => 'Address not verified.',
+        'J' => 'Card member’s name, billing address, and postal code match. Shipping information verified and chargeback protection guaranteed through the Fraud Protection Program.',
+        'K' => 'Card member’s name matches but billing address and billing postal code do not match.',
+        'L' => 'Card member’s name and billing postal code match, but billing address does not match.',
+        'M' => 'Street address and postal code match.',
+        'N' => 'Street address and postal code do not match.',
+        'O' => 'Card member’s name and billing address match, but billing postal code does not match.',
+        'P' => 'Postal code matches, but street address not verified.',
+        'Q' => 'Card member’s name, billing address, and postal code match. Shipping information verified but chargeback protection not guaranteed.',
+        'R' => 'System unavailable.',
+        'S' => 'U.S.-issuing bank does not support AVS.',
+        'T' => 'Card member’s name does not match, but street address matches.',
+        'U' => 'Address information unavailable.',
+        'V' => 'Card member’s name, billing address, and billing postal code match.',
+        'W' => 'Street address does not match, but 9-digit postal code matches.',
+        'X' => 'Street address and 9-digit postal code match.',
+        'Y' => 'Street address and 5-digit postal code match.',
+        'Z' => 'Street address does not match, but 5-digit postal code matches.'
+      }
+      
+      # Map vendor's AVS result code to a postal match code
+      POSTAL_MATCH_CODE = {
+        'Y' => %w( D H F H J L M P Q V W X Y Z ),
+        'N' => %w( A C K N O ),
+        'X' => %w( G S ),
+        nil => %w( B E I R T U )
+      }.inject({}) do |map, (type, codes)|
+        codes.each { |code| map[code] = type }
+        map
+      end
+      
+      # Map vendor's AVS result code to a street match code
+      STREET_MATCH_CODE = {
+        'Y' => %w( A B D H J M O Q T V X Y ),
+        'N' => %w( C K L N P W Z ),
+        'X' => %w( G S ),
+        nil => %w( E F I R U )
+      }.inject({}) do |map, (type, codes)|
+        codes.each { |code| map[code] = type }
+        map
+      end
+      
+      attr_reader :code, :message, :street_match, :postal_match
+      
+      def self.messages
+        MESSAGES
+      end
+      
+      def initialize(attrs)
+        attrs ||= {}
+        
+        @code = attrs[:code].upcase unless attrs[:code].blank?
+        @message = self.class.messages[code]
+        
+        if attrs[:street_match].blank?
+          @street_match = STREET_MATCH_CODE[code]
+        else  
+          @street_match = attrs[:street_match].upcase
+        end
+          
+        if attrs[:postal_match].blank?
+          @postal_match = POSTAL_MATCH_CODE[code]
+        else  
+          @postal_match = attrs[:postal_match].upcase
+        end
+      end
+    
+      def to_hash
+        { 'code' => code,
+          'message' => message,
+          'street_match' => street_match,
+          'postal_match' => postal_match
+        }
+      end
+    end
+  end
+end

data/lib/active_merchant/billing/base.rb

@@ -31,7 +31,7 @@ module ActiveMerchant #:nodoc:
       # 
       #   ActiveMerchant::Billing::Base.gateway('moneris').new
       def self.gateway(name)
-        ActiveMerchant::Billing.const_get("#{name.to_s.downcase}_gateway".camelize)
+        Billing.const_get("#{name.to_s.downcase}_gateway".camelize)
       end
       
 
@@ -45,8 +45,13 @@ module ActiveMerchant #:nodoc:
       #   notification = chronopay.notification(raw_post)
       #
       def self.integration(name)
-        ActiveMerchant::Billing::Integrations.const_get("#{name.to_s.downcase}".camelize)
-      end 
+        Billing::Integrations.const_get("#{name.to_s.downcase}".camelize)
+      end
+      
+      # A check to see if we're in test mode
+      def self.test?
+        self.gateway_mode == :test
+      end
     end             
   end
 end

data/lib/active_merchant/billing/check.rb

@@ -0,0 +1,61 @@
+module ActiveMerchant #:nodoc:
+  module Billing #:nodoc:
+    # The Check object is a plain old Ruby object, similar to CreditCard. It supports validation
+    # of necessary attributes such as checkholder's name, routing and account numbers, but it is
+    # not backed by any database.
+    # 
+    # You may use Check in place of CreditCard with any gateway that supports it. Currently, only
+    # +BrainTreeGateway+ supports the Check object.
+    class Check
+      include Validateable
+      
+      attr_accessor :name, :routing_number, :account_number, :account_holder_type, :account_type
+      
+      def initialize(args={})
+        args = args.with_indifferent_access
+        self.name           = args[:name]
+        self.routing_number = args[:routing_number]
+        self.account_number = args[:account_number]
+        self.account_holder_type = args[:account_holder_type]
+        self.account_type   = args[:account_type]
+      end
+      
+      def validate
+        for attr in [:name, :routing_number, :account_number]
+          errors.add(attr, "cannot be empty") if self.send(attr).blank?
+        end
+        
+        errors.add(:routing_number, "is invalid") unless valid_routing_number?
+        
+        errors.add(:account_holder_type, "must be personal or business") if
+            !account_holder_type.blank? && !%w[business personal].include?(account_holder_type.to_s)
+        
+        errors.add(:account_type, "must be checking or savings") if
+            !account_type.blank? && !%w[checking savings].include?(account_type.to_s)
+      end
+      
+      def type
+        'check'
+      end
+      
+      # Routing numbers may be validated by calculating a checksum and dividing it by 10. The
+      # formula is:
+      #   (3(d1 + d4 + d7) + 7(d2 + d5 + d8) + 1(d3 + d6 + d9))mod 10 = 0
+      # See http://en.wikipedia.org/wiki/Routing_transit_number#Internal_checksums
+      def valid_routing_number?
+        d = routing_number.to_s.split('').map(&:to_i).select { |d| (0..9).include?(d) }
+        case d.size
+          when 9 then
+            checksum = ((3 * (d[0] + d[3] + d[6])) +
+                        (7 * (d[1] + d[4] + d[7])) +
+                             (d[2] + d[5] + d[8])) % 10
+            case checksum
+              when 0 then true
+              else        false
+            end
+          else false
+        end
+      end
+    end
+  end
+end

data/lib/active_merchant/billing/credit_card.rb

@@ -1,111 +1,77 @@
 require 'time'
 require 'date'
+require 'active_merchant/billing/expiry_date'
 
 module ActiveMerchant #:nodoc:
   module Billing #:nodoc:
+    # == Description
     # This credit card object can be used as a stand alone object. It acts just like an ActiveRecord object
     # but doesn't support the .save method as its not backed by a database.
+    # 
+    # For testing purposes, use the 'bogus' credit card type. This card skips the vast majority of 
+    # validations. This allows you to focus on your core concerns until you're ready to be more concerned 
+    # with the details of particular creditcards or your gateway.
+    # 
+    # == Testing With CreditCard
+    # Often when testing we don't care about the particulars of a given card type. When using the 'test' 
+    # mode in your Gateway, there are six different valid card numbers: 1, 2, 3, 'success', 'fail', 
+    # and 'error'.
+    # 
+    #--
+    # For details, see CreditCardMethods#valid_number?
+    #++
+    # 
+    # == Example Usage
+    #   cc = CreditCard.new(
+    #     :first_name => 'Steve', 
+    #     :last_name  => 'Smith', 
+    #     :month      => '9', 
+    #     :year       => '2010', 
+    #     :type       => 'visa', 
+    #     :number     => '4242424242424242'
+    #   )
+    #   
+    #   cc.valid? # => true
+    #   cc.display_number # => XXXX-XXXX-XXXX-4242
+    #
     class CreditCard
       include CreditCardMethods
       include Validateable
       
+      ## Attributes
+      
       cattr_accessor :require_verification_value
-      self.require_verification_value = false
+      self.require_verification_value = true
       
-      def self.requires_verification_value?
-        require_verification_value
-      end
-        
-      class ExpiryDate #:nodoc:
-        attr_reader :month, :year
-        def initialize(month, year)
-          @month = month
-          @year = year
-        end
-
-        def expired? #:nodoc:
-          Time.now > expiration rescue true
-        end
-
-        def expiration #:nodoc:
-          Time.parse("#{month}/#{month_days}/#{year} 23:59:59") rescue Time.at(0)
-        end
-
-        private
-        def month_days
-          mdays = [nil,31,28,31,30,31,30,31,31,30,31,30,31]
-          mdays[2] = 29 if Date.leap?(year)
-          mdays[month]
-        end
-      end 
-
-      # required
+      # Essential attributes for a valid, non-bogus creditcards
       attr_accessor :number, :month, :year, :type, :first_name, :last_name
       
-      # required for Switch / Solo
+      # Required for Switch / Solo cards
       attr_accessor :start_month, :start_year, :issue_number
 
-      # Optional verification_value (CVV, CVV2 etc)
-      #
-      # Gateways will try their best to run validation on the passed in value if it is supplied
-      #
+      # Optional verification_value (CVV, CVV2 etc). Gateways will try their best to 
+      # run validation on the passed in value if it is supplied
       attr_accessor :verification_value
 
-      def before_validate
-        self.type.downcase! if type.respond_to?(:downcase)
-        self.month = month.to_i
-        self.year = year.to_i
-        self.number.to_s.gsub!(/[^\d]/, "")
+      # Provides proxy access to an expiry date object
+      def expiry_date
+        ExpiryDate.new(@month, @year)
       end
 
-      def validate
-        errors.add :year, "expired"                             if expired?
-                   
-        errors.add :first_name, "cannot be empty"               if @first_name.blank?
-        errors.add :last_name, "cannot be empty"                if @last_name.blank?
-        errors.add :month, "is not a valid month"               unless valid_month?(@month)
-        errors.add :year, "is not a valid year"                 unless valid_expiry_year?(@year)
-
-        # Bogus card is pretty much for testing purposes. Lets just skip these extra tests if its used
-        
-        return if type == 'bogus'
-
-        errors.add :number, "is not a valid credit card number" unless CreditCard.valid_number?(number)
-        errors.add :type, "is required" if type.blank?
-        errors.add :type, "is invalid"  unless CreditCard.card_companies.keys.include?(type)
-          
-        unless errors.on(:number) || errors.on(:type)
-          CreditCard.type?(number) == type or
-            errors.add :type, "is not the correct card type"
-        end
-
-        if CreditCard.requires_verification_value?
-          errors.add :verification_value, "is required" unless verification_value?
-        end
-        
-        if [ 'switch', 'solo' ].include?(type)
-          unless valid_month?(@start_month) && valid_start_year?(@start_year) || valid_issue_number?(@issue_number)
-            errors.add :start_month, "is invalid"                    unless valid_month?(@start_month)
-            errors.add :start_year, "is invalid"                     unless valid_start_year?(@start_year)
-            errors.add :issue_number, "cannot be empty"              unless valid_issue_number?(@issue_number)
-          end
-        end
-      end  
-      
       def expired?
         expiry_date.expired?
       end
       
       def name?
-        @first_name != nil and @last_name != nil
+        first_name? && last_name?
       end
       
       def first_name?
-        @first_name != nil
+        !@first_name.blank?
       end
       
       def last_name?
-        @last_name != nil
+        !@last_name.blank?
       end
             
       def name
@@ -118,15 +84,73 @@ module ActiveMerchant #:nodoc:
 
       # Show the card number, with all but last 4 numbers replace with "X". (XXXX-XXXX-XXXX-4338)
       def display_number
-        "XXXX-XXXX-XXXX-#{last_digits}"
+        self.class.mask(number)
       end
       
       def last_digits
-        number.nil? ? "" : number.last(4)
+        self.class.last_digits(number)
       end
+      
+      def validate
+        validate_essential_attributes
 
-      def expiry_date
-        ExpiryDate.new(@month, @year)
+        # Bogus card is pretty much for testing purposes. Lets just skip these extra tests if its used
+        return if type == 'bogus'
+
+        validate_card_type
+        validate_card_number
+        validate_verification_value
+        validate_switch_or_solo_attributes
+      end
+      
+      def self.requires_verification_value?
+        require_verification_value
+      end
+      
+      private
+      
+      def before_validate #:nodoc: 
+        self.month = month.to_i
+        self.year  = year.to_i
+        self.number.to_s.gsub!(/[^\d]/, "")
+        self.type.downcase! if type.respond_to?(:downcase)
+        self.type = self.class.type?(number) if type.blank?
+      end
+      
+      def validate_card_number #:nodoc:
+        errors.add :number, "is not a valid credit card number" unless CreditCard.valid_number?(number)
+        unless errors.on(:number) || errors.on(:type)
+          errors.add :type, "is not the correct card type" unless CreditCard.matching_type?(number, type)
+        end
+      end
+      
+      def validate_card_type #:nodoc:
+        errors.add :type, "is required" if type.blank?
+        errors.add :type, "is invalid"  unless CreditCard.card_companies.keys.include?(type)
+      end
+      
+      def validate_essential_attributes #:nodoc:
+        errors.add :first_name, "cannot be empty"      if @first_name.blank?
+        errors.add :last_name,  "cannot be empty"      if @last_name.blank?
+        errors.add :month,      "is not a valid month" unless valid_month?(@month)
+        errors.add :year,       "expired"              if expired?
+        errors.add :year,       "is not a valid year"  unless valid_expiry_year?(@year)
+      end
+      
+      def validate_switch_or_solo_attributes #:nodoc:
+        if %w[switch solo].include?(type)
+          unless valid_month?(@start_month) && valid_start_year?(@start_year) || valid_issue_number?(@issue_number)
+            errors.add :start_month,  "is invalid"      unless valid_month?(@start_month)
+            errors.add :start_year,   "is invalid"      unless valid_start_year?(@start_year)
+            errors.add :issue_number, "cannot be empty" unless valid_issue_number?(@issue_number)
+          end
+        end
+      end
+      
+      def validate_verification_value #:nodoc:
+        if CreditCard.requires_verification_value?
+          errors.add :verification_value, "is required" unless verification_value? 
+        end
       end
     end
   end