Class: ActiveMerchant::Billing::CreditCard

Inherits:
Model
  • Object
show all
Includes:
CreditCardMethods
Defined in:
lib/active_merchant/billing/credit_card.rb

Overview

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

  • Dankort

  • Maestro

  • Forbrugsforeningen

  • Sodexo

  • Vr

  • Carnet

  • Synchrony

  • Routex

  • Elo

  • Alelo

  • Cabal

  • Naranja

  • UnionPay

  • Alia

  • Olimpica

  • Creditel

  • Confiable

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 ActiveMerchant::Billing::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

Direct Known Subclasses

NetworkTokenizationCreditCard

Defined Under Namespace

Classes: ExpiryDate

Constant Summary collapse

READ_METHOD_DESCRIPTIONS =
{
  nil => 'A card reader was not used.',
  'fallback_no_chip' => 'Magstripe was read because the card has no chip.',
  'fallback_chip_error' => "Magstripe was read because the card's chip failed.",
  'contactless' => 'Data was read by a Contactless EMV kernel. Issuer script results are not available.',
  'contactless_magstripe' => 'Contactless data was read with a non-EMV protocol.',
  'contact' => 'Data was read using the EMV protocol. Issuer script results may follow.',
  'contact_quickchip' => 'Data was read by the Quickchip EMV kernel. Issuer script results are not available.'
}

Constants included from CreditCardMethods

ActiveMerchant::Billing::CreditCardMethods::ALELO_RANGES, ActiveMerchant::Billing::CreditCardMethods::CABAL_RANGES, ActiveMerchant::Billing::CreditCardMethods::CARD_COMPANY_DETECTORS, ActiveMerchant::Billing::CreditCardMethods::CARNET_BINS, ActiveMerchant::Billing::CreditCardMethods::CARNET_RANGES, ActiveMerchant::Billing::CreditCardMethods::CARTES_BANCAIRES_RANGES, ActiveMerchant::Billing::CreditCardMethods::ELECTRON_RANGES, ActiveMerchant::Billing::CreditCardMethods::ELO_RANGES, ActiveMerchant::Billing::CreditCardMethods::JCB_RANGES, ActiveMerchant::Billing::CreditCardMethods::MAESTRO_BINS, ActiveMerchant::Billing::CreditCardMethods::MAESTRO_RANGES, ActiveMerchant::Billing::CreditCardMethods::MASTERCARD_RANGES, ActiveMerchant::Billing::CreditCardMethods::NARANJA_RANGES, ActiveMerchant::Billing::CreditCardMethods::UNIONPAY_RANGES

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from CreditCardMethods

#card_verification_value_length, #credit_card?, #electron?, in_bin_range?, included, #valid_card_verification_value?, #valid_expiry_year?, #valid_issue_number?, #valid_month?, #valid_start_year?

Methods inherited from Model

#initialize

Methods included from ActiveMerchant::Billing::Compatibility::Model

#errors, #valid?

Constructor Details

This class inherits a constructor from ActiveMerchant::Billing::Model

Class Attribute Details

.require_nameObject

Returns the value of attribute require_name.



67
68
69
# File 'lib/active_merchant/billing/credit_card.rb', line 67

def require_name
  @require_name
end

.require_verification_valueObject

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



66
67
68
# File 'lib/active_merchant/billing/credit_card.rb', line 66

def require_verification_value
  @require_verification_value
end

Instance Attribute Details

#encrypted_pin_cryptogramString

Returns the ciphertext of the card’s encrypted PIN.

Returns:

  • (String)


215
216
217
# File 'lib/active_merchant/billing/credit_card.rb', line 215

def encrypted_pin_cryptogram
  @encrypted_pin_cryptogram
end

#encrypted_pin_ksnString

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

Returns:

  • (String)


220
221
222
# File 'lib/active_merchant/billing/credit_card.rb', line 220

def encrypted_pin_ksn
  @encrypted_pin_ksn
end

#first_nameString

Returns or sets the first name of the card holder.

Returns:

  • (String)


139
140
141
# File 'lib/active_merchant/billing/credit_card.rb', line 139

def first_name
  @first_name
end

#icc_dataString

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

Returns:

  • (String)


195
196
197
# File 'lib/active_merchant/billing/credit_card.rb', line 195

def icc_data
  @icc_data
end

#last_nameString

Returns or sets the last name of the card holder.

Returns:

  • (String)


144
145
146
# File 'lib/active_merchant/billing/credit_card.rb', line 144

def last_name
  @last_name
end

#manual_entrytrue, false

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.

Returns:

  • (true, false)


190
191
192
# File 'lib/active_merchant/billing/credit_card.rb', line 190

def manual_entry
  @manual_entry
end

#monthInteger (readonly)

Returns or sets the expiry month for the card.

Returns:

  • (Integer)


85
86
87
# File 'lib/active_merchant/billing/credit_card.rb', line 85

def month
  @month
end

#numberString

Returns or sets the credit card number.

Returns:

  • (String)


76
77
78
# File 'lib/active_merchant/billing/credit_card.rb', line 76

def number
  @number
end

#read_methodString

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

Returns:

  • (String)


200
201
202
# File 'lib/active_merchant/billing/credit_card.rb', line 200

def read_method
  @read_method
end

#track_dataString

Returns or sets the track data for the card

Returns:

  • (String)


181
182
183
# File 'lib/active_merchant/billing/credit_card.rb', line 181

def track_data
  @track_data
end

#verification_valueString

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.

Returns:

  • (String)

    the verification value



153
154
155
# File 'lib/active_merchant/billing/credit_card.rb', line 153

def verification_value
  @verification_value
end

#yearInteger (readonly)

Returns or sets the expiry year for the card.

Returns:

  • (Integer)


90
91
92
# File 'lib/active_merchant/billing/credit_card.rb', line 90

def year
  @year
end

Class Method Details

.requires_name?Boolean

Returns:

  • (Boolean)


332
333
334
# File 'lib/active_merchant/billing/credit_card.rb', line 332

def self.requires_name?
  require_name
end

.requires_verification_value?Boolean

Returns:

  • (Boolean)


328
329
330
# File 'lib/active_merchant/billing/credit_card.rb', line 328

def self.requires_verification_value?
  require_verification_value
end

Instance Method Details

#brandString

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’

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

Returns:

  • (String)

    the credit card brand



123
124
125
126
127
128
129
# File 'lib/active_merchant/billing/credit_card.rb', line 123

def brand
  if !defined?(@brand) || empty?(@brand)
    self.class.brand?(number)
  else
    @brand
  end
end

#brand=(value) ⇒ Object



131
132
133
134
# File 'lib/active_merchant/billing/credit_card.rb', line 131

def brand=(value)
  value = value && value.to_s.dup
  @brand = (value.respond_to?(:downcase) ? value.downcase : value)
end

#display_numberString

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.

Examples:

credit_card = CreditCard.new(:number => "2132542376824338")
credit_card.display_number  # "XXXX-XXXX-XXXX-4338"

Returns:

  • (String)

    a display-friendly version of the card number



301
302
303
# File 'lib/active_merchant/billing/credit_card.rb', line 301

def display_number
  self.class.mask(number)
end

#emv?Boolean

Returns:

  • (Boolean)


336
337
338
# File 'lib/active_merchant/billing/credit_card.rb', line 336

def emv?
  icc_data.present?
end

#expired?Boolean

Returns whether the credit card has expired.

Returns:

  • (Boolean)

    true if the card has expired, false otherwise



242
243
244
# File 'lib/active_merchant/billing/credit_card.rb', line 242

def expired?
  expiry_date.expired?
end

#expiry_dateExpiryDate

Provides proxy access to an expiry date object

Returns:



235
236
237
# File 'lib/active_merchant/billing/credit_card.rb', line 235

def expiry_date
  ExpiryDate.new(@month, @year)
end

#first_digitsObject



305
306
307
# File 'lib/active_merchant/billing/credit_card.rb', line 305

def first_digits
  self.class.first_digits(number)
end

#first_name?Boolean

Returns whether the first_name attribute has been set.

Returns:

  • (Boolean)


252
253
254
# File 'lib/active_merchant/billing/credit_card.rb', line 252

def first_name?
  first_name.present?
end

#last_digitsObject



309
310
311
# File 'lib/active_merchant/billing/credit_card.rb', line 309

def last_digits
  self.class.last_digits(number)
end

#last_name?Boolean

Returns whether the last_name attribute has been set.

Returns:

  • (Boolean)


257
258
259
# File 'lib/active_merchant/billing/credit_card.rb', line 257

def last_name?
  last_name.present?
end

#nameString

Returns the full name of the card holder.

Returns:

  • (String)

    the full name of the card holder



264
265
266
# File 'lib/active_merchant/billing/credit_card.rb', line 264

def name
  "#{first_name} #{last_name}".strip
end

#name=(full_name) ⇒ Object



268
269
270
271
272
# File 'lib/active_merchant/billing/credit_card.rb', line 268

def name=(full_name)
  names = full_name.split
  self.last_name  = names.pop
  self.first_name = names.join(' ')
end

#name?Boolean

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

Returns:

  • (Boolean)


247
248
249
# File 'lib/active_merchant/billing/credit_card.rb', line 247

def name?
  first_name? || last_name?
end

#require_verification_value=(value) ⇒ Boolean

Sets if the credit card requires a verification value.

Returns:

  • (Boolean)


158
159
160
161
# File 'lib/active_merchant/billing/credit_card.rb', line 158

def require_verification_value=(value)
  @require_verification_value_set = true
  @require_verification_value = value
end

#requires_verification_value?Boolean

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`.

Returns:

  • (Boolean)


169
170
171
172
173
174
175
176
# File 'lib/active_merchant/billing/credit_card.rb', line 169

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

#typeObject



222
223
224
225
# File 'lib/active_merchant/billing/credit_card.rb', line 222

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) ⇒ Object



227
228
229
230
# File 'lib/active_merchant/billing/credit_card.rb', line 227

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

#validateObject

Validates the credit card details.

Any validation errors are added to the ActiveMerchant::Billing::Compatibility::Model#errors attribute.



316
317
318
319
320
321
322
323
324
325
326
# File 'lib/active_merchant/billing/credit_card.rb', line 316

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?Boolean

Returns:

  • (Boolean)


287
288
289
# File 'lib/active_merchant/billing/credit_card.rb', line 287

def verification_value?
  !verification_value.blank?
end