Class: ActiveMerchant::Billing::CreditCard

Inherits:
Object
  • Object
show all
Includes:
CreditCardMethods, Validateable
Defined in:
lib/active_merchant/billing/credit_card.rb,
lib/active_merchant/billing/expiry_date.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.valid? # => true
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

included, #valid_expiry_year?, #valid_issue_number?, #valid_month?, #valid_start_year?

Instance Attribute 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



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

def brand
  @brand
end

#first_name ⇒ String

Returns or sets the first name of the card holder.

Returns:

  • (String) 


96
97
98
 
# File 'lib/active_merchant/billing/credit_card.rb', line 96

def first_name
  @first_name
end

#issue_number ⇒ Object

Required for Switch / Solo cards



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

def issue_number
  @issue_number
end

#last_name ⇒ String

Returns or sets the last name of the card holder.

Returns:

  • (String) 


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

def last_name
  @last_name
end

#month ⇒ Integer

Returns or sets the expiry month for the card.

Returns:

  • (Integer) 


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

def month
  @month
end

#number ⇒ String

Returns or sets the credit card number.

Returns:

  • (String) 


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

def number
  @number
end

#start_month ⇒ Object

Required for Switch / Solo cards



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

def start_month
  @start_month
end

#start_year ⇒ Object

Required for Switch / Solo cards



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

def start_year
  @start_year
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



113
114
115
 
# File 'lib/active_merchant/billing/credit_card.rb', line 113

def verification_value
  @verification_value
end

#year ⇒ Integer

Returns or sets the expiry year for the card.

Returns:

  • (Integer) 


69
70
71
 
# File 'lib/active_merchant/billing/credit_card.rb', line 69

def year
  @year
end

Class Method Details

.requires_verification_value? ⇒ Boolean

Returns:

  • (Boolean) 


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

def self.requires_verification_value?
  require_verification_value
end

Instance Method Details

#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



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

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



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

def expired?
  expiry_date.expired?
end

#expiry_date ⇒ ExpiryDate

Provides proxy access to an expiry date object

Returns:



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

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

#first_digits ⇒ Object 



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

def first_digits
  self.class.first_digits(number)
end

#first_name? ⇒ Boolean

Returns whether the first_name attribute has been set.

Returns:

  • (Boolean) 


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

def first_name?
  @first_name.present?
end

#last_digits ⇒ Object 



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

def last_digits
  self.class.last_digits(number)
end

#last_name? ⇒ Boolean

Returns whether the last_name attribute has been set.

Returns:

  • (Boolean) 


150
151
152
 
# File 'lib/active_merchant/billing/credit_card.rb', line 150

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



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

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

#name=(full_name) ⇒ Object 



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

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) 


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

def name?
  first_name? || last_name?
end

#type ⇒ Object 



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

def type
  self.class.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 



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

def type=(value)
  self.class.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 #errors attribute.



196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/active_merchant/billing/credit_card.rb', line 196

def validate
  validate_essential_attributes

  # Bogus card is pretty much for testing purposes. Lets just skip these extra tests if its used
  return if brand == 'bogus'

  validate_card_brand
  validate_card_number
  validate_verification_value
  validate_switch_or_solo_attributes
end

#verification_value? ⇒ Boolean

Returns:

  • (Boolean) 


167
168
169
 
# File 'lib/active_merchant/billing/credit_card.rb', line 167

def verification_value?
  !@verification_value.blank?
end