Class: ActiveMerchant::Billing::CreditCard
- 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
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
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_NO_LUHN, ActiveMerchant::Billing::CreditCardMethods::UNIONPAY_RANGES, ActiveMerchant::Billing::CreditCardMethods::VERVE_RANGES
Class Attribute Summary collapse
-
.require_name ⇒ Object
Returns the value of attribute require_name.
-
.require_verification_value ⇒ Object
Inherited, but can be overridden w/o changing parent’s value.
Instance Attribute Summary collapse
-
#encrypted_pin_cryptogram ⇒ String
Returns the ciphertext of the card’s encrypted PIN.
-
#encrypted_pin_ksn ⇒ String
Returns the Key Serial Number (KSN) of the card’s encrypted PIN.
-
#first_name ⇒ String
Returns or sets the first name of the card holder.
-
#icc_data ⇒ String
Returns or sets the ICC/ASN1 credit card data for a EMV transaction, typically this is a BER-encoded TLV string.
-
#last_name ⇒ String
Returns or sets the last name of the card holder.
-
#manual_entry ⇒ true, false
Returns or sets whether a card has been processed using manual entry.
-
#month ⇒ Integer
readonly
Returns or sets the expiry month for the card.
-
#number ⇒ String
Returns or sets the credit card number.
-
#read_method ⇒ String
Returns or sets information about the source of the card data.
-
#track_data ⇒ String
Returns or sets the track data for the card.
-
#verification_value ⇒ String
Returns or sets the card verification value.
-
#year ⇒ Integer
readonly
Returns or sets the expiry year for the card.
Class Method Summary collapse
Instance Method Summary collapse
- #allow_spaces_in_card?(number = nil) ⇒ Boolean
-
#brand ⇒ String
Returns or sets the credit card brand.
- #brand=(value) ⇒ Object
-
#display_number ⇒ String
Returns a display-friendly version of the card number.
- #emv? ⇒ Boolean
-
#expired? ⇒ Boolean
Returns whether the credit card has expired.
-
#expiry_date ⇒ ExpiryDate
Provides proxy access to an expiry date object.
- #first_digits ⇒ Object
-
#first_name? ⇒ Boolean
Returns whether the
first_name
attribute has been set. - #last_digits ⇒ Object
-
#last_name? ⇒ Boolean
Returns whether the
last_name
attribute has been set. -
#name ⇒ String
Returns the full name of the card holder.
- #name=(full_name) ⇒ Object
-
#name? ⇒ Boolean
Returns whether either the
first_name
or thelast_name
attributes has been set. -
#require_verification_value=(value) ⇒ Boolean
Sets if the credit card requires a verification value.
-
#requires_verification_value? ⇒ Boolean
Returns if this credit card needs a verification value.
- #type ⇒ Object
- #type=(value) ⇒ Object
-
#validate ⇒ Object
Validates the credit card details.
- #verification_value? ⇒ Boolean
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
Methods included from ActiveMerchant::Billing::Compatibility::Model
Constructor Details
This class inherits a constructor from ActiveMerchant::Billing::Model
Class Attribute Details
.require_name ⇒ Object
Returns the value of attribute require_name.
77 78 79 |
# File 'lib/active_merchant/billing/credit_card.rb', line 77 def require_name @require_name end |
.require_verification_value ⇒ Object
Inherited, but can be overridden w/o changing parent’s value
76 77 78 |
# File 'lib/active_merchant/billing/credit_card.rb', line 76 def require_verification_value @require_verification_value end |
Instance Attribute Details
#encrypted_pin_cryptogram ⇒ String
Returns the ciphertext of the card’s encrypted PIN.
233 234 235 |
# File 'lib/active_merchant/billing/credit_card.rb', line 233 def encrypted_pin_cryptogram @encrypted_pin_cryptogram end |
#encrypted_pin_ksn ⇒ String
Returns the Key Serial Number (KSN) of the card’s encrypted PIN.
238 239 240 |
# File 'lib/active_merchant/billing/credit_card.rb', line 238 def encrypted_pin_ksn @encrypted_pin_ksn end |
#first_name ⇒ String
Returns or sets the first name of the card holder.
157 158 159 |
# File 'lib/active_merchant/billing/credit_card.rb', line 157 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.
213 214 215 |
# File 'lib/active_merchant/billing/credit_card.rb', line 213 def icc_data @icc_data end |
#last_name ⇒ String
Returns or sets the last name of the card holder.
162 163 164 |
# File 'lib/active_merchant/billing/credit_card.rb', line 162 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.
208 209 210 |
# File 'lib/active_merchant/billing/credit_card.rb', line 208 def manual_entry @manual_entry end |
#month ⇒ Integer (readonly)
Returns or sets the expiry month for the card.
95 96 97 |
# File 'lib/active_merchant/billing/credit_card.rb', line 95 def month @month end |
#number ⇒ String
Returns or sets the credit card number.
86 87 88 |
# File 'lib/active_merchant/billing/credit_card.rb', line 86 def number @number end |
#read_method ⇒ String
Returns or sets information about the source of the card data.
218 219 220 |
# File 'lib/active_merchant/billing/credit_card.rb', line 218 def read_method @read_method end |
#track_data ⇒ String
Returns or sets the track data for the card
199 200 201 |
# File 'lib/active_merchant/billing/credit_card.rb', line 199 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.
171 172 173 |
# File 'lib/active_merchant/billing/credit_card.rb', line 171 def verification_value @verification_value end |
#year ⇒ Integer (readonly)
Returns or sets the expiry year for the card.
100 101 102 |
# File 'lib/active_merchant/billing/credit_card.rb', line 100 def year @year end |
Class Method Details
.requires_name? ⇒ Boolean
350 351 352 |
# File 'lib/active_merchant/billing/credit_card.rb', line 350 def self.requires_name? require_name end |
.requires_verification_value? ⇒ Boolean
346 347 348 |
# File 'lib/active_merchant/billing/credit_card.rb', line 346 def self.requires_verification_value? require_verification_value end |
Instance Method Details
#allow_spaces_in_card?(number = nil) ⇒ Boolean
358 359 360 |
# File 'lib/active_merchant/billing/credit_card.rb', line 358 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’
Or, if you wish to test your implementation, ‘bogus’.
141 142 143 144 145 146 147 |
# File 'lib/active_merchant/billing/credit_card.rb', line 141 def brand if !defined?(@brand) || empty?(@brand) self.class.brand?(number) else @brand end end |
#brand=(value) ⇒ Object
149 150 151 152 |
# File 'lib/active_merchant/billing/credit_card.rb', line 149 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.
319 320 321 |
# File 'lib/active_merchant/billing/credit_card.rb', line 319 def display_number self.class.mask(number) end |
#emv? ⇒ Boolean
354 355 356 |
# File 'lib/active_merchant/billing/credit_card.rb', line 354 def emv? icc_data.present? end |
#expired? ⇒ Boolean
Returns whether the credit card has expired.
260 261 262 |
# File 'lib/active_merchant/billing/credit_card.rb', line 260 def expired? expiry_date.expired? end |
#expiry_date ⇒ ExpiryDate
Provides proxy access to an expiry date object
253 254 255 |
# File 'lib/active_merchant/billing/credit_card.rb', line 253 def expiry_date ExpiryDate.new(@month, @year) end |
#first_digits ⇒ Object
323 324 325 |
# File 'lib/active_merchant/billing/credit_card.rb', line 323 def first_digits self.class.first_digits(number) end |
#first_name? ⇒ Boolean
Returns whether the first_name
attribute has been set.
270 271 272 |
# File 'lib/active_merchant/billing/credit_card.rb', line 270 def first_name? first_name.present? end |
#last_digits ⇒ Object
327 328 329 |
# File 'lib/active_merchant/billing/credit_card.rb', line 327 def last_digits self.class.last_digits(number) end |
#last_name? ⇒ Boolean
Returns whether the last_name
attribute has been set.
275 276 277 |
# File 'lib/active_merchant/billing/credit_card.rb', line 275 def last_name? last_name.present? end |
#name ⇒ String
Returns the full name of the card holder.
282 283 284 |
# File 'lib/active_merchant/billing/credit_card.rb', line 282 def name "#{first_name} #{last_name}".strip end |
#name=(full_name) ⇒ Object
286 287 288 289 290 |
# File 'lib/active_merchant/billing/credit_card.rb', line 286 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.
265 266 267 |
# File 'lib/active_merchant/billing/credit_card.rb', line 265 def name? first_name? || last_name? end |
#require_verification_value=(value) ⇒ Boolean
Sets if the credit card requires a verification value.
176 177 178 179 |
# File 'lib/active_merchant/billing/credit_card.rb', line 176 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`.
187 188 189 190 191 192 193 194 |
# File 'lib/active_merchant/billing/credit_card.rb', line 187 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
240 241 242 243 |
# File 'lib/active_merchant/billing/credit_card.rb', line 240 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
245 246 247 248 |
# File 'lib/active_merchant/billing/credit_card.rb', line 245 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.
334 335 336 337 338 339 340 341 342 343 344 |
# File 'lib/active_merchant/billing/credit_card.rb', line 334 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
305 306 307 |
# File 'lib/active_merchant/billing/credit_card.rb', line 305 def verification_value? !verification_value.blank? end |