class ActiveMerchant::Billing::CreditCard

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:

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               => '2017',
  :brand              => 'visa',
  :number             => '4242424242424242',
  :verification_value => '424'
)

cc.validate # => {}
cc.display_number # => XXXX-XXXX-XXXX-4242

Constants

BRANDS_WITH_SPACES_IN_NUMBER
READ_METHOD_DESCRIPTIONS

Attributes

require_name[RW]
require_verification_value[RW]

Inherited, but can be overridden w/o changing parent’s value

encrypted_pin_cryptogram[RW]

Returns the ciphertext of the card’s encrypted PIN.

@return [String]

encrypted_pin_ksn[RW]

Returns the Key Serial Number (KSN) of the card’s encrypted PIN.

@return [String]

first_name[RW]

Returns or sets the first name of the card holder.

@return [String]

icc_data[RW]

Returns or sets the ICC/ASN1 credit card data for a EMV transaction, typically this is a BER-encoded TLV string.

@return [String]

last_name[RW]

Returns or sets the last name of the card holder.

@return [String]

manual_entry[RW]

Returns or sets whether a card has been processed using manual entry.

This attribute is optional and is only used by gateways who use this information in their transaction risk calculations. See this page on ‘card not present’ transactions for further explanation and examples of this kind of transaction.

@return [true, false]

month[R]

Returns or sets the expiry month for the card.

@return [Integer]

number[R]

Returns or sets the credit card number.

@return [String]

read_method[RW]

Returns or sets information about the source of the card data.

@return [String]

track_data[RW]

Returns or sets the track data for the card

@return [String]

verification_value[RW]

Returns or sets the card verification value.

This attribute is optional but recommended. The verification value is a card security code. If provided, the gateway will attempt to validate the value.

@return [String] the verification value

year[R]

Returns or sets the expiry year for the card.

@return [Integer]

Public Class Methods

requires_name?() click to toggle source
# File lib/active_merchant/billing/credit_card.rb, line 354
def self.requires_name?
  require_name
end
requires_verification_value?() click to toggle source
# File lib/active_merchant/billing/credit_card.rb, line 350
def self.requires_verification_value?
  require_verification_value
end

Public Instance Methods

allow_spaces_in_card?(number = nil) click to toggle source
# File lib/active_merchant/billing/credit_card.rb, line 362
def allow_spaces_in_card?(number = nil)
  BRANDS_WITH_SPACES_IN_NUMBER.include?(self.class.brand?(self.number || number))
end
brand() click to toggle source

Returns or sets the credit card brand.

Valid card types are

  • +‘visa’+

  • +‘master’+

  • +‘discover’+

  • +‘american_express’+

  • +‘diners_club’+

  • +‘jcb’+

  • +‘dankort’+

  • +‘maestro’+

  • +‘forbrugsforeningen’+

  • +‘sodexo’+

  • +‘vr’+

  • +‘carnet’+

  • +‘synchrony’+

  • +‘routex’+

  • +‘elo’+

  • +‘alelo’+

  • +‘cabal’+

  • +‘naranja’+

  • +‘union_pay’+

  • +‘alia’+

  • +‘olimpica’+

  • +‘creditel’+

  • +‘confiable’+

  • +‘mada’+

  • +‘bp_plus’+

  • +‘passcard’+

  • +‘edenred’+

  • +‘anda’+

  • +‘tarjeta-d’+

  • +‘panal’+

  • +‘verve’+

  • +‘tuya’+

  • +‘uatp’+

Or, if you wish to test your implementation, +‘bogus’+.

@return (String) the credit card brand

# File lib/active_merchant/billing/credit_card.rb, line 145
def brand
  if !defined?(@brand) || empty?(@brand)
    self.class.brand?(number)
  else
    @brand
  end
end
brand=(value) click to toggle source
# File lib/active_merchant/billing/credit_card.rb, line 153
def brand=(value)
  value = value && value.to_s.dup
  @brand = (value.respond_to?(:downcase) ? value.downcase : value)
end
display_number() click to toggle source

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

# File lib/active_merchant/billing/credit_card.rb, line 323
def display_number
  self.class.mask(number)
end
emv?() click to toggle source
# File lib/active_merchant/billing/credit_card.rb, line 358
def emv?
  icc_data.present?
end
expired?() click to toggle source

Returns whether the credit card has expired.

@return true if the card has expired, false otherwise

# File lib/active_merchant/billing/credit_card.rb, line 264
def expired?
  expiry_date.expired?
end
expiry_date() click to toggle source

Provides proxy access to an expiry date object

@return [ExpiryDate]

# File lib/active_merchant/billing/credit_card.rb, line 257
def expiry_date
  ExpiryDate.new(@month, @year)
end
first_digits() click to toggle source
# File lib/active_merchant/billing/credit_card.rb, line 327
def first_digits
  self.class.first_digits(number)
end
first_name?() click to toggle source

Returns whether the first_name attribute has been set.

# File lib/active_merchant/billing/credit_card.rb, line 274
def first_name?
  first_name.present?
end
last_digits() click to toggle source
# File lib/active_merchant/billing/credit_card.rb, line 331
def last_digits
  self.class.last_digits(number)
end
last_name?() click to toggle source

Returns whether the last_name attribute has been set.

# File lib/active_merchant/billing/credit_card.rb, line 279
def last_name?
  last_name.present?
end
name() click to toggle source

Returns the full name of the card holder.

@return [String] the full name of the card holder

# File lib/active_merchant/billing/credit_card.rb, line 286
def name
  "#{first_name} #{last_name}".strip
end
name=(full_name) click to toggle source
# File lib/active_merchant/billing/credit_card.rb, line 290
def name=(full_name)
  names = full_name.split
  self.last_name  = names.pop
  self.first_name = names.join(' ')
end
name?() click to toggle source

Returns whether either the first_name or the last_name attributes has been set.

# File lib/active_merchant/billing/credit_card.rb, line 269
def name?
  first_name? || last_name?
end
number=(value) click to toggle source
# File lib/active_merchant/billing/credit_card.rb, line 90
def number=(value)
  @number = (empty?(value) ? value : filter_number(value))
end
require_verification_value=(value) click to toggle source

Sets if the credit card requires a verification value.

@return [Boolean]

# File lib/active_merchant/billing/credit_card.rb, line 180
def require_verification_value=(value)
  @require_verification_value_set = true
  @require_verification_value = value
end
requires_verification_value?() click to toggle source

Returns if this credit card needs a verification value.

By default this returns the configured value from ‘CreditCard.require_verification_value`, but one can set a per instance requirement with `credit_card.require_verification_value = false`.

@return [Boolean]

# File lib/active_merchant/billing/credit_card.rb, line 191
def requires_verification_value?
  @require_verification_value_set ||= false
  if @require_verification_value_set
    @require_verification_value
  else
    self.class.requires_verification_value?
  end
end
type() click to toggle source
# File lib/active_merchant/billing/credit_card.rb, line 244
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
type=(value) click to toggle source
# File lib/active_merchant/billing/credit_card.rb, line 249
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
validate() click to toggle source

Validates the credit card details.

Any validation errors are added to the {#errors} attribute.

# File lib/active_merchant/billing/credit_card.rb, line 338
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
  )
end
verification_value?() click to toggle source
# File lib/active_merchant/billing/credit_card.rb, line 309
def verification_value?
  !verification_value.blank?
end

Private Instance Methods

filter_number(value) click to toggle source
# File lib/active_merchant/billing/credit_card.rb, line 368
def filter_number(value)
  regex = if allow_spaces_in_card?(value)
            /[^\d ]/
          else
            /[^\d]/
          end
  value.to_s.gsub(regex, '')
end