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

  • Mada

  • BpPlus

  • Passcard

  • Edenred

  • Anda

  • Creditos directos (Tarjeta D)

  • Panal

  • Verve

  • Tuya

  • UATP

  • Patagonia365

  • Tarjeta Sol

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

BRANDS_WITH_SPACES_IN_NUMBER = 
%w(bp_plus)
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::HIPERCARD_RANGES, ActiveMerchant::Billing::CreditCardMethods::JCB_RANGES, ActiveMerchant::Billing::CreditCardMethods::MADA_RANGES, ActiveMerchant::Billing::CreditCardMethods::MAESTRO_BINS, ActiveMerchant::Billing::CreditCardMethods::MAESTRO_RANGES, ActiveMerchant::Billing::CreditCardMethods::MASTERCARD_RANGES, ActiveMerchant::Billing::CreditCardMethods::NARANJA_RANGES, ActiveMerchant::Billing::CreditCardMethods::PANAL_RANGES, ActiveMerchant::Billing::CreditCardMethods::SODEXO_BINS, ActiveMerchant::Billing::CreditCardMethods::SODEXO_NO_LUHN, ActiveMerchant::Billing::CreditCardMethods::UNIONPAY_RANGES, ActiveMerchant::Billing::CreditCardMethods::VERVE_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?

Methods included from Rails::Model

#valid?

Constructor Details

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

Class Attribute Details

.require_name ⇒ Object

Returns the value of attribute require_name.



81
82
83
 
# File 'lib/active_merchant/billing/credit_card.rb', line 81

def require_name
  @require_name
end

.require_verification_value ⇒ Object

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



80
81
82
 
# File 'lib/active_merchant/billing/credit_card.rb', line 80

def require_verification_value
  @require_verification_value
end

Instance Attribute Details

#encrypted_pin_cryptogram ⇒ String

Returns the ciphertext of the card’s encrypted PIN.

Returns:

  • (String) 


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

def encrypted_pin_cryptogram
  @encrypted_pin_cryptogram
end

#encrypted_pin_ksn ⇒ String

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

Returns:

  • (String) 


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

def encrypted_pin_ksn
  @encrypted_pin_ksn
end

#first_name ⇒ String

Returns or sets the first name of the card holder.

Returns:

  • (String) 


165
166
167
 
# File 'lib/active_merchant/billing/credit_card.rb', line 165

def first_name
  @first_name
end

#icc_data ⇒ String

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

Returns:

  • (String) 


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

def icc_data
  @icc_data
end

#last_name ⇒ String

Returns or sets the last name of the card holder.

Returns:

  • (String) 


170
171
172
 
# File 'lib/active_merchant/billing/credit_card.rb', line 170

def last_name
  @last_name
end

#manual_entry ⇒ true, 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) 


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

def manual_entry
  @manual_entry
end

#month ⇒ Integer (readonly)

Returns or sets the expiry month for the card.

Returns:

  • (Integer) 


99
100
101
 
# File 'lib/active_merchant/billing/credit_card.rb', line 99

def month
  @month
end

#number ⇒ String

Returns or sets the credit card number.

Returns:

  • (String) 


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

def number
  @number
end

#read_method ⇒ String

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

Returns:

  • (String) 


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

def read_method
  @read_method
end

#track_data ⇒ String

Returns or sets the track data for the card

Returns:

  • (String) 


207
208
209
 
# File 'lib/active_merchant/billing/credit_card.rb', line 207

def track_data
  @track_data
end

#verification_value ⇒ String

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



179
180
181
 
# File 'lib/active_merchant/billing/credit_card.rb', line 179

def verification_value
  @verification_value
end

#year ⇒ Integer (readonly)

Returns or sets the expiry year for the card.

Returns:

  • (Integer) 


104
105
106
 
# File 'lib/active_merchant/billing/credit_card.rb', line 104

def year
  @year
end

Class Method Details

.requires_name? ⇒ Boolean

Returns:

  • (Boolean) 


358
359
360
 
# File 'lib/active_merchant/billing/credit_card.rb', line 358

def self.requires_name?
  require_name
end

.requires_verification_value? ⇒ Boolean

Returns:

  • (Boolean) 


354
355
356
 
# File 'lib/active_merchant/billing/credit_card.rb', line 354

def self.requires_verification_value?
  require_verification_value
end

Instance Method Details

#allow_spaces_in_card?(number = nil) ⇒ Boolean

Returns:

  • (Boolean) 


366
367
368
 
# File 'lib/active_merchant/billing/credit_card.rb', line 366

def allow_spaces_in_card?(number = nil)
  BRANDS_WITH_SPACES_IN_NUMBER.include?(self.class.brand?(self.number || number))
end

#brand ⇒ String

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’

  • ‘patagonia_365’

  • ‘tarjeta_sol’

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

Returns:

  • (String) —

    the credit card brand



149
150
151
152
153
154
155
 
# File 'lib/active_merchant/billing/credit_card.rb', line 149

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

#brand=(value) ⇒ Object 



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

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

#display_number ⇒ String

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



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

def display_number
  self.class.mask(number)
end

#emv? ⇒ Boolean

Returns:

  • (Boolean) 


362
363
364
 
# File 'lib/active_merchant/billing/credit_card.rb', line 362

def emv?
  icc_data.present?
end

#encrypted_wallet? ⇒ Boolean

Returns:

  • (Boolean) 


378
379
380
 
# File 'lib/active_merchant/billing/credit_card.rb', line 378

def encrypted_wallet?
  false
end

#expired? ⇒ Boolean

Returns whether the credit card has expired.

Returns:

  • (Boolean) —

    true if the card has expired, false otherwise



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

def expired?
  expiry_date.expired?
end

#expiry_date ⇒ ExpiryDate

Provides proxy access to an expiry date object

Returns:



261
262
263
 
# File 'lib/active_merchant/billing/credit_card.rb', line 261

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

#first_digits ⇒ Object 



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

def first_digits
  self.class.first_digits(number)
end

#first_name? ⇒ Boolean

Returns whether the first_name attribute has been set.

Returns:

  • (Boolean) 


278
279
280
 
# File 'lib/active_merchant/billing/credit_card.rb', line 278

def first_name?
  first_name.present?
end

#last_digits ⇒ Object 



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

def last_digits
  self.class.last_digits(number)
end

#last_name? ⇒ Boolean

Returns whether the last_name attribute has been set.

Returns:

  • (Boolean) 


283
284
285
 
# File 'lib/active_merchant/billing/credit_card.rb', line 283

def last_name?
  last_name.present?
end

#mobile_wallet? ⇒ Boolean

Returns:

  • (Boolean) 


374
375
376
 
# File 'lib/active_merchant/billing/credit_card.rb', line 374

def mobile_wallet?
  false
end

#name ⇒ String

Returns the full name of the card holder.

Returns:

  • (String) —

    the full name of the card holder



290
291
292
 
# File 'lib/active_merchant/billing/credit_card.rb', line 290

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

#name=(full_name) ⇒ Object 



294
295
296
297
298
 
# File 'lib/active_merchant/billing/credit_card.rb', line 294

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) 


273
274
275
 
# File 'lib/active_merchant/billing/credit_card.rb', line 273

def name?
  first_name? || last_name?
end

#network_token? ⇒ Boolean

Returns:

  • (Boolean) 


370
371
372
 
# File 'lib/active_merchant/billing/credit_card.rb', line 370

def network_token?
  false
end

#require_verification_value=(value) ⇒ Boolean

Sets if the credit card requires a verification value.

Returns:

  • (Boolean) 


184
185
186
187
 
# File 'lib/active_merchant/billing/credit_card.rb', line 184

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) 


195
196
197
198
199
200
201
202
 
# File 'lib/active_merchant/billing/credit_card.rb', line 195

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



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

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 



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

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

Validates the credit card details.

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



342
343
344
345
346
347
348
349
350
351
352
 
# File 'lib/active_merchant/billing/credit_card.rb', line 342

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) 


313
314
315
 
# File 'lib/active_merchant/billing/credit_card.rb', line 313

def verification_value?
  !verification_value.blank?
end