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

  • 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 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

Constants included from CreditCardMethods

ActiveMerchant::Billing::CreditCardMethods::CARD_COMPANIES, ActiveMerchant::Billing::CreditCardMethods::ELECTRON_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?, 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_name ⇒ Object

Returns the value of attribute require_name.



56
57
58
 
# File 'lib/active_merchant/billing/credit_card.rb', line 56

def require_name
  @require_name
end

.require_verification_value ⇒ Object

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



55
56
57
 
# File 'lib/active_merchant/billing/credit_card.rb', line 55

def require_verification_value
  @require_verification_value
end

Instance Attribute Details

#contactless_emv ⇒ true, false

Returns or sets whether card-present EMV data has been read contactlessly.

Returns:

  • (true, false) 


188
189
190
 
# File 'lib/active_merchant/billing/credit_card.rb', line 188

def contactless_emv
  @contactless_emv
end

#contactless_magstripe ⇒ true, false

Returns or sets whether card-present magstripe data has been read contactlessly.

Returns:

  • (true, false) 


193
194
195
 
# File 'lib/active_merchant/billing/credit_card.rb', line 193

def contactless_magstripe
  @contactless_magstripe
end

#encrypted_pin_cryptogram ⇒ String

Returns the ciphertext of the card’s encrypted PIN.

Returns:

  • (String) 


198
199
200
 
# File 'lib/active_merchant/billing/credit_card.rb', line 198

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) 


203
204
205
 
# File 'lib/active_merchant/billing/credit_card.rb', line 203

def encrypted_pin_ksn
  @encrypted_pin_ksn
end

#fallback_reason ⇒ String

Returns or sets a fallback reason for a EMV transaction whereby the customer’s card entered a fallback scenario. This can be an arbitrary string.

Returns:

  • (String) 


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

def fallback_reason
  @fallback_reason
end

#first_name ⇒ String

Returns or sets the first name of the card holder.

Returns:

  • (String) 


117
118
119
 
# File 'lib/active_merchant/billing/credit_card.rb', line 117

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) 


177
178
179
 
# File 'lib/active_merchant/billing/credit_card.rb', line 177

def icc_data
  @icc_data
end

#issue_number ⇒ Object

Returns the value of attribute issue_number.



126
127
128
 
# File 'lib/active_merchant/billing/credit_card.rb', line 126

def issue_number
  @issue_number
end

#last_name ⇒ String

Returns or sets the last name of the card holder.

Returns:

  • (String) 


122
123
124
 
# File 'lib/active_merchant/billing/credit_card.rb', line 122

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) 


172
173
174
 
# File 'lib/active_merchant/billing/credit_card.rb', line 172

def manual_entry
  @manual_entry
end

#month ⇒ Integer (readonly)

Returns or sets the expiry month for the card.

Returns:

  • (Integer) 


74
75
76
 
# File 'lib/active_merchant/billing/credit_card.rb', line 74

def month
  @month
end

#number ⇒ String

Returns or sets the credit card number.

Returns:

  • (String) 


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

def number
  @number
end

#start_month ⇒ Object (readonly)

Required for Switch / Solo cards



125
126
127
 
# File 'lib/active_merchant/billing/credit_card.rb', line 125

def start_month
  @start_month
end

#start_year ⇒ Object (readonly)

Required for Switch / Solo cards



125
126
127
 
# File 'lib/active_merchant/billing/credit_card.rb', line 125

def start_year
  @start_year
end

#track_data ⇒ String

Returns or sets the track data for the card

Returns:

  • (String) 


163
164
165
 
# File 'lib/active_merchant/billing/credit_card.rb', line 163

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



135
136
137
 
# File 'lib/active_merchant/billing/credit_card.rb', line 135

def verification_value
  @verification_value
end

#year ⇒ Integer (readonly)

Returns or sets the expiry year for the card.

Returns:

  • (Integer) 


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

def year
  @year
end

Class Method Details

.requires_name? ⇒ Boolean

Returns:

  • (Boolean) 


316
317
318
 
# File 'lib/active_merchant/billing/credit_card.rb', line 316

def self.requires_name?
  require_name
end

.requires_verification_value? ⇒ Boolean

Returns:

  • (Boolean) 


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

def self.requires_verification_value?
  require_verification_value
end

Instance Method Details

#brand ⇒ String

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

Returns:

  • (String) —

    the credit card brand



101
102
103
104
105
106
107
 
# File 'lib/active_merchant/billing/credit_card.rb', line 101

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

#brand=(value) ⇒ Object 



109
110
111
112
 
# File 'lib/active_merchant/billing/credit_card.rb', line 109

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



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

def display_number
  self.class.mask(number)
end

#emv? ⇒ Boolean

Returns:

  • (Boolean) 


320
321
322
 
# File 'lib/active_merchant/billing/credit_card.rb', line 320

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



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

def expired?
  expiry_date.expired?
end

#expiry_date ⇒ ExpiryDate

Provides proxy access to an expiry date object

Returns:



218
219
220
 
# File 'lib/active_merchant/billing/credit_card.rb', line 218

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

#first_digits ⇒ Object 



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

def first_digits
  self.class.first_digits(number)
end

#first_name? ⇒ Boolean

Returns whether the first_name attribute has been set.

Returns:

  • (Boolean) 


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

def first_name?
  first_name.present?
end

#last_digits ⇒ Object 



292
293
294
 
# File 'lib/active_merchant/billing/credit_card.rb', line 292

def last_digits
  self.class.last_digits(number)
end

#last_name? ⇒ Boolean

Returns whether the last_name attribute has been set.

Returns:

  • (Boolean) 


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

def last_name?
  last_name.present?
end

#name ⇒ String

Returns the full name of the card holder.

Returns:

  • (String) —

    the full name of the card holder



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

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

#name=(full_name) ⇒ Object 



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

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) 


230
231
232
 
# File 'lib/active_merchant/billing/credit_card.rb', line 230

def name?
  first_name? || last_name?
end

#require_verification_value=(value) ⇒ Boolean

Sets if the credit card requires a verification value.

Returns:

  • (Boolean) 


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

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) 


151
152
153
154
155
156
157
158
 
# File 'lib/active_merchant/billing/credit_card.rb', line 151

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 



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

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 



210
211
212
213
 
# File 'lib/active_merchant/billing/credit_card.rb', line 210

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.



299
300
301
302
303
304
305
306
307
308
309
310
 
# File 'lib/active_merchant/billing/credit_card.rb', line 299

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

#verification_value? ⇒ Boolean

Returns:

  • (Boolean) 


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

def verification_value?
  !verification_value.blank?
end