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

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

Defined Under Namespace

Classes: ExpiryDate

Constant Summary

Constants included from CreditCardMethods

ActiveMerchant::Billing::CreditCardMethods::CARD_COMPANIES

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from CreditCardMethods

#card_verification_value_length, 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

Instance Attribute Details

#first_name ⇒ String

Returns or sets the first name of the card holder.

Returns:

  • (String) 


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

def first_name
  @first_name
end

#issue_number ⇒ Object

Returns the value of attribute issue_number.



119
120
121
 
# File 'lib/active_merchant/billing/credit_card.rb', line 119

def issue_number
  @issue_number
end

#last_name ⇒ String

Returns or sets the last name of the card holder.

Returns:

  • (String) 


115
116
117
 
# File 'lib/active_merchant/billing/credit_card.rb', line 115

def last_name
  @last_name
end

#month ⇒ Integer (readonly)

Returns or sets the expiry month for the card.

Returns:

  • (Integer) 


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

def month
  @month
end

#number ⇒ String

Returns or sets the credit card number.

Returns:

  • (String) 


58
59
60
 
# File 'lib/active_merchant/billing/credit_card.rb', line 58

def number
  @number
end

#start_month ⇒ Object (readonly)

Required for Switch / Solo cards



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

def start_month
  @start_month
end

#start_year ⇒ Object (readonly)

Required for Switch / Solo cards



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

def start_year
  @start_year
end

#track_data ⇒ String

Returns or sets the track data for the card

Returns:

  • (String) 


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

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



128
129
130
 
# File 'lib/active_merchant/billing/credit_card.rb', line 128

def verification_value
  @verification_value
end

#year ⇒ Integer (readonly)

Returns or sets the expiry year for the card.

Returns:

  • (Integer) 


72
73
74
 
# File 'lib/active_merchant/billing/credit_card.rb', line 72

def year
  @year
end

Class Method Details

.requires_verification_value? ⇒ Boolean

Returns:

  • (Boolean) 


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

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



94
95
96
97
98
99
100
 
# File 'lib/active_merchant/billing/credit_card.rb', line 94

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

#brand=(value) ⇒ Object 



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

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



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

def display_number
  self.class.mask(number)
end

#expired? ⇒ Boolean

Returns whether the credit card has expired.

Returns:

  • (Boolean) —

    true if the card has expired, false otherwise



155
156
157
 
# File 'lib/active_merchant/billing/credit_card.rb', line 155

def expired?
  expiry_date.expired?
end

#expiry_date ⇒ ExpiryDate

Provides proxy access to an expiry date object

Returns:



148
149
150
 
# File 'lib/active_merchant/billing/credit_card.rb', line 148

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

#first_digits ⇒ Object 



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

def first_digits
  self.class.first_digits(number)
end

#first_name? ⇒ Boolean

Returns whether the first_name attribute has been set.

Returns:

  • (Boolean) 


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

def first_name?
  first_name.present?
end

#last_digits ⇒ Object 



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

def last_digits
  self.class.last_digits(number)
end

#last_name? ⇒ Boolean

Returns whether the last_name attribute has been set.

Returns:

  • (Boolean) 


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

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



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

def name
  [first_name, last_name].compact.join(' ')
end

#name=(full_name) ⇒ Object 



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

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) 


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

def name?
  first_name? || last_name?
end

#type ⇒ Object 



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

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 



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

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.



229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/active_merchant/billing/credit_card.rb', line 229

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) 


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

def verification_value?
  !verification_value.blank?
end