aktivemerchant 2.0.0

data/lib/active_merchant/billing/credit_card.rb

@@ -0,0 +1,352 @@
+require 'time'
+require 'date'
+require "active_merchant/billing/model"
+
+module ActiveMerchant #:nodoc:
+  module Billing #:nodoc:
+    # A +CreditCard+ object represents a physical credit card, and is capable of validating the various
+    # data associated with these.
+    #
+    # At the moment, the following credit card types are supported:
+    #
+    # * Visa
+    # * MasterCard
+    # * Discover
+    # * American Express
+    # * Diner's Club
+    # * JCB
+    # * Switch
+    # * Solo
+    # * Dankort
+    # * Maestro
+    # * Forbrugsforeningen
+    # * Laser
+    #
+    # For testing purposes, use the 'bogus' credit card brand. This skips the vast majority of
+    # validations, allowing you to focus on your core concerns until you're ready to be more concerned
+    # with the details of particular credit cards or your gateway.
+    #
+    # == Testing With CreditCard
+    # Often when testing we don't care about the particulars of a given card brand. 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::ClassMethods#valid_number?}
+    #
+    # == Example Usage
+    #   cc = CreditCard.new(
+    #     :first_name => 'Steve',
+    #     :last_name  => 'Smith',
+    #     :month      => '9',
+    #     :year       => '2010',
+    #     :brand      => 'visa',
+    #     :number     => '4242424242424242'
+    #   )
+    #
+    #   cc.validate # => {}
+    #   cc.display_number # => XXXX-XXXX-XXXX-4242
+    #
+    class CreditCard < Model
+      include CreditCardMethods
+
+      cattr_accessor :require_verification_value
+      self.require_verification_value = true
+
+      # Returns or sets the credit card number.
+      #
+      # @return [String]
+      attr_reader :number
+
+      def number=(value)
+        @number = (empty?(value) ? value : value.to_s.gsub(/[^\d]/, ""))
+      end
+
+      # Returns or sets the expiry month for the card.
+      #
+      # @return [Integer]
+      attr_reader :month
+
+      # Returns or sets the expiry year for the card.
+      #
+      # @return [Integer]
+      attr_reader :year
+
+      # Returns or sets the credit card brand.
+      #
+      # Valid card types are
+      #
+      # * +'visa'+
+      # * +'master'+
+      # * +'discover'+
+      # * +'american_express'+
+      # * +'diners_club'+
+      # * +'jcb'+
+      # * +'switch'+
+      # * +'solo'+
+      # * +'dankort'+
+      # * +'maestro'+
+      # * +'forbrugsforeningen'+
+      # * +'laser'+
+      #
+      # Or, if you wish to test your implementation, +'bogus'+.
+      #
+      # @return (String) the credit card brand
+      def brand
+        if !defined?(@brand) || empty?(@brand)
+          self.class.brand?(number)
+        else
+          @brand
+        end
+      end
+
+      def brand=(value)
+        value = value && value.to_s.dup
+        @brand = (value.respond_to?(:downcase) ? value.downcase : value)
+      end
+
+      # Returns or sets the first name of the card holder.
+      #
+      # @return [String]
+      attr_accessor :first_name
+
+      # Returns or sets the last name of the card holder.
+      #
+      # @return [String]
+      attr_accessor :last_name
+
+      # Required for Switch / Solo cards
+      attr_reader :start_month, :start_year
+      attr_accessor :issue_number
+
+      # Returns or sets the card verification value.
+      #
+      # This attribute is optional but recommended. The verification value is
+      # a {card security code}[http://en.wikipedia.org/wiki/Card_security_code]. If provided,
+      # the gateway will attempt to validate the value.
+      #
+      # @return [String] the verification value
+      attr_accessor :verification_value
+
+      # Returns or sets the track data for the card
+      #
+      # @return [String]
+      attr_accessor :track_data
+
+      def type
+        ActiveMerchant.deprecated "CreditCard#type is deprecated and will be removed from a future release of ActiveMerchant. Please use CreditCard#brand instead."
+        brand
+      end
+
+      def type=(value)
+        ActiveMerchant.deprecated "CreditCard#type is deprecated and will be removed from a future release of ActiveMerchant. Please use CreditCard#brand instead."
+        self.brand = value
+      end
+
+      # Provides proxy access to an expiry date object
+      #
+      # @return [ExpiryDate]
+      def expiry_date
+        ExpiryDate.new(@month, @year)
+      end
+
+      # Returns whether the credit card has expired.
+      #
+      # @return +true+ if the card has expired, +false+ otherwise
+      def expired?
+        expiry_date.expired?
+      end
+
+      # Returns whether either the +first_name+ or the +last_name+ attributes has been set.
+      def name?
+        first_name? || last_name?
+      end
+
+      # Returns whether the +first_name+ attribute has been set.
+      def first_name?
+        first_name.present?
+      end
+
+      # Returns whether the +last_name+ attribute has been set.
+      def last_name?
+        last_name.present?
+      end
+
+      # Returns the full name of the card holder.
+      #
+      # @return [String] the full name of the card holder
+      def name
+        [first_name, last_name].compact.join(' ')
+      end
+
+      def name=(full_name)
+        names = full_name.split
+        self.last_name  = names.pop
+        self.first_name = names.join(" ")
+      end
+
+      %w(month year start_month start_year).each do |m|
+        class_eval %(
+          def #{m}=(v)
+            @#{m} = case v
+            when "", nil, 0
+              nil
+            else
+              v.to_i
+            end
+          end
+        )
+      end
+
+      def verification_value?
+        !verification_value.blank?
+      end
+
+      # Returns a display-friendly version of the card number.
+      #
+      # All but the last 4 numbers are replaced with an "X", and hyphens are
+      # inserted in order to improve legibility.
+      #
+      # @example
+      #   credit_card = CreditCard.new(:number => "2132542376824338")
+      #   credit_card.display_number  # "XXXX-XXXX-XXXX-4338"
+      #
+      # @return [String] a display-friendly version of the card number
+      def display_number
+        self.class.mask(number)
+      end
+
+      def first_digits
+        self.class.first_digits(number)
+      end
+
+      def last_digits
+        self.class.last_digits(number)
+      end
+
+      # Validates the credit card details.
+      #
+      # Any validation errors are added to the {#errors} attribute.
+      def validate
+        errors = validate_essential_attributes + validate_verification_value
+
+        # Bogus card is pretty much for testing purposes. Lets just skip these extra tests if its used
+        return errors_hash(errors) if brand == 'bogus'
+
+        errors_hash(
+          errors +
+          validate_card_brand_and_number +
+          validate_switch_or_solo_attributes
+        )
+      end
+
+      def self.requires_verification_value?
+        require_verification_value
+      end
+
+      private
+
+      def validate_essential_attributes #:nodoc:
+        errors = []
+
+        errors << [:first_name, "cannot be empty"] if first_name.blank?
+        errors << [:last_name,  "cannot be empty"] if last_name.blank?
+
+        if(empty?(month) || empty?(year))
+          errors << [:month, "is required"] if empty?(month)
+          errors << [:year,  "is required"] if empty?(year)
+        else
+          errors << [:month, "is not a valid month"] if !valid_month?(month)
+
+          if expired?
+            errors << [:year,  "expired"]
+          else
+            errors << [:year,  "is not a valid year"]  if !valid_expiry_year?(year)
+          end
+        end
+
+        errors
+      end
+
+      def validate_card_brand_and_number #:nodoc:
+        errors = []
+
+        if !empty?(brand)
+          errors << [:brand, "is invalid"]  if !CreditCard.card_companies.keys.include?(brand)
+        end
+
+        if empty?(number)
+          errors << [:number, "is required"]
+        elsif !CreditCard.valid_number?(number)
+          errors << [:number, "is not a valid credit card number"]
+        end
+
+        if errors.empty?
+          errors << [:brand, "does not match the card number"] if !CreditCard.matching_brand?(number, brand)
+        end
+
+        errors
+      end
+
+      def validate_verification_value #:nodoc:
+        errors = []
+
+        if verification_value?
+          unless valid_card_verification_value?(verification_value, brand)
+            errors << [:verification_value, "should be #{card_verification_value_length(brand)} digits"]
+          end
+        elsif CreditCard.requires_verification_value?
+          errors << [:verification_value, "is required"]
+        end
+        errors
+      end
+
+      def validate_switch_or_solo_attributes #:nodoc:
+        errors = []
+
+        if %w[switch solo].include?(brand)
+          valid_start_month = valid_month?(start_month)
+          valid_start_year = valid_start_year?(start_year)
+
+          if((!valid_start_month || !valid_start_year) && !valid_issue_number?(issue_number))
+            if empty?(issue_number)
+              errors << [:issue_number, "cannot be empty"]
+              errors << [:start_month, "is invalid"] if !valid_start_month
+              errors << [:start_year,  "is invalid"] if !valid_start_year
+            else
+              errors << [:issue_number, "is invalid"] if !valid_issue_number?(issue_number)
+            end
+          end
+        end
+
+        errors
+      end
+
+      class ExpiryDate #:nodoc:
+        attr_reader :month, :year
+        def initialize(month, year)
+          @month = month.to_i
+          @year = year.to_i
+        end
+
+        def expired? #:nodoc:
+          Time.now.utc > expiration
+        end
+
+        def expiration #:nodoc:
+          begin
+            Time.utc(year, month, month_days, 23, 59, 59)
+          rescue ArgumentError
+            Time.at(0).utc
+          end
+        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
+    end
+  end
+end

data/lib/active_merchant/billing/credit_card_formatting.rb

@@ -0,0 +1,24 @@
+module ActiveMerchant #:nodoc:
+  module Billing #:nodoc:
+    module CreditCardFormatting
+
+      def expdate(credit_card)
+        "#{format(credit_card.month, :two_digits)}#{format(credit_card.year, :two_digits)}"
+      end
+
+      # This method is used to format numerical information pertaining to credit cards.
+      #
+      #   format(2005, :two_digits)  # => "05"
+      #   format(05,   :four_digits) # => "0005"
+      def format(number, option)
+        return '' if number.blank?
+
+        case option
+          when :two_digits  ; sprintf("%.2i", number.to_i)[-2..-1]
+          when :four_digits ; sprintf("%.4i", number.to_i)[-4..-1]
+          else number
+        end
+      end
+    end
+  end
+end

data/lib/active_merchant/billing/credit_card_methods.rb

@@ -0,0 +1,160 @@
+module ActiveMerchant #:nodoc:
+  module Billing #:nodoc:
+    # Convenience methods that can be included into a custom Credit Card object, such as an ActiveRecord based Credit Card object.
+    module CreditCardMethods
+      CARD_COMPANIES = {
+        'visa'               => /^4\d{12}(\d{3})?$/,
+        'master'             => /^(5[1-5]\d{4}|677189)\d{10}$/,
+        'discover'           => /^(6011|65\d{2}|64[4-9]\d)\d{12}|(62\d{14})$/,
+        'american_express'   => /^3[47]\d{13}$/,
+        'diners_club'        => /^3(0[0-5]|[68]\d)\d{11}$/,
+        'jcb'                => /^35(28|29|[3-8]\d)\d{12}$/,
+        'switch'             => /^6759\d{12}(\d{2,3})?$/,
+        'solo'               => /^6767\d{12}(\d{2,3})?$/,
+        'dankort'            => /^5019\d{12}$/,
+        'maestro'            => /^(5[06-8]|6\d)\d{10,17}$/,
+        'forbrugsforeningen' => /^600722\d{10}$/,
+        'laser'              => /^(6304|6706|6709|6771(?!89))\d{8}(\d{4}|\d{6,7})?$/
+      }
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      def valid_month?(month)
+        (1..12).include?(month.to_i)
+      end
+
+      def valid_expiry_year?(year)
+        (Time.now.year..Time.now.year + 20).include?(year.to_i)
+      end
+
+      def valid_start_year?(year)
+        ((year.to_s =~ /^\d{4}$/) && (year.to_i > 1987))
+      end
+
+      # Credit card providers have 3 digit verification values
+      # This isn't standardised, these are called various names such as
+      # CVC, CVV, CID, CSC and more
+      # See: http://en.wikipedia.org/wiki/Card_security_code
+      # American Express is the exception with 4 digits
+      #
+      # Below are links from the card providers with their requirements
+      # visa:             http://usa.visa.com/personal/security/3-digit-security-code.jsp
+      # master:           http://www.mastercard.com/ca/merchant/en/getstarted/Anatomy_MasterCard.html
+      # jcb:              http://www.jcbcard.com/security/info.html
+      # diners_club:      http://www.dinersclub.com/assets/DinersClub_card_ID_features.pdf
+      # discover:         https://www.discover.com/credit-cards/help-center/glossary.html
+      # american_express: https://online.americanexpress.com/myca/fuidfyp/us/action?request_type=un_fuid&Face=en_US
+      def valid_card_verification_value?(cvv, brand)
+        cvv.to_s =~ /^\d{#{card_verification_value_length(brand)}}$/
+      end
+      
+      def card_verification_value_length(brand)
+        brand == 'american_express' ? 4 : 3
+      end
+      
+      def valid_issue_number?(number)
+        (number.to_s =~ /^\d{1,2}$/)
+      end
+
+      module ClassMethods
+        # Returns true if it validates. Optionally, you can pass a card brand as an argument and
+        # make sure it is of the correct brand.
+        #
+        # References:
+        # - http://perl.about.com/compute/perl/library/nosearch/P073000.htm
+        # - http://www.beachnet.com/~hstiles/cardtype.html
+        def valid_number?(number)
+          valid_test_mode_card_number?(number) ||
+            valid_card_number_length?(number) &&
+            valid_checksum?(number)
+        end
+
+        # Regular expressions for the known card companies.
+        #
+        # References:
+        # - http://en.wikipedia.org/wiki/Credit_card_number
+        # - http://www.barclaycardbusiness.co.uk/information_zone/processing/bin_rules.html
+        def card_companies
+          CARD_COMPANIES
+        end
+
+        # Returns a string containing the brand of card from the list of known information below.
+        # Need to check the cards in a particular order, as there is some overlap of the allowable ranges
+        #--
+        # TODO Refactor this method. We basically need to tighten up the Maestro Regexp.
+        #
+        # Right now the Maestro regexp overlaps with the MasterCard regexp (IIRC). If we can tighten
+        # things up, we can boil this whole thing down to something like...
+        #
+        #   def brand?(number)
+        #     return 'visa' if valid_test_mode_card_number?(number)
+        #     card_companies.find([nil]) { |brand, regexp| number =~ regexp }.first.dup
+        #   end
+        #
+        def brand?(number)
+          return 'bogus' if valid_test_mode_card_number?(number)
+
+          card_companies.reject { |c,p| c == 'maestro' }.each do |company, pattern|
+            return company.dup if number =~ pattern
+          end
+
+          return 'maestro' if number =~ card_companies['maestro']
+
+          return nil
+        end
+
+        def type?(number)
+          ActiveMerchant.deprecated "CreditCard#type? is deprecated and will be removed from a future release of ActiveMerchant. Please use CreditCard#brand? instead."
+          brand?(number)
+        end
+
+        def first_digits(number)
+          number.to_s.slice(0,6)
+        end
+
+        def last_digits(number)
+          number.to_s.length <= 4 ? number : number.to_s.slice(-4..-1)
+        end
+
+        def mask(number)
+          "XXXX-XXXX-XXXX-#{last_digits(number)}"
+        end
+
+        # Checks to see if the calculated brand matches the specified brand
+        def matching_brand?(number, brand)
+          brand?(number) == brand
+        end
+
+        def matching_type?(number, brand)
+          ActiveMerchant.deprecated "CreditCard#matching_type? is deprecated and will be removed from a future release of ActiveMerchant. Please use CreditCard#matching_brand? instead."
+          matching_brand?(number, brand)
+        end
+
+        private
+
+        def valid_card_number_length?(number) #:nodoc:
+          number.to_s.length >= 12
+        end
+
+        def valid_test_mode_card_number?(number) #:nodoc:
+          ActiveMerchant::Billing::Base.test? &&
+            %w[1 2 3 success failure error].include?(number.to_s)
+        end
+
+        # Checks the validity of a card number by use of the Luhn Algorithm.
+        # Please see http://en.wikipedia.org/wiki/Luhn_algorithm for details.
+        def valid_checksum?(number) #:nodoc:
+          sum = 0
+          for i in 0..number.length
+            weight = number[-1 * (i + 2), 1].to_i * (2 - (i % 2))
+            sum += (weight < 10) ? weight : weight - 9
+          end
+
+          (number[-1,1].to_i == (10 - sum % 10) % 10)
+        end
+      end
+    end
+  end
+end