credit_card_validations 8.1.0 → 9.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ea48b31cccd9e050dd0e59cdd71bb784cf319d355dfa2eb0a185635308b1b81
-  data.tar.gz: 3c0358bce72eeb6f265ffb0130dc3a5a843dbf326ef989c118d827c025b8e0c3
+  metadata.gz: d26fc84c0dd18fbfcacaeead238fe16ecefe51486e4122e63c3dcf4836fd4ce6
+  data.tar.gz: a1bad2adea7168439991cf98bb68a25a2d62c4372602cbe54743f23eda12c11e
 SHA512:
-  metadata.gz: 62586d60302f937ec7f47a98440d89767fba557506a5568733e498e2c41d491d5d8f283923590808abc4f1ab3ebe3466dcadb8fbd4a21b721d07337ea4e34133
-  data.tar.gz: 366c5f5239778f08035b207b9d1e88e2f3c5f747913b3d86c79b1555fd571a640d16eca7121e78b62fe93f87298a05b9bb9161c7acfe1dcdad2e6a6b100662b2
+  metadata.gz: 14d43e6661c30034f8f52f4bf0558eb4704843ad048dfb79943a0822f4f1d6b221d31a98bd1b73dd23cd3a6d76904fdc88b6758abfb5ea1a701da001e938b73a
+  data.tar.gz: c41da3b3de8f45d93413a41c4fe88c8e543eea2c8e149ea8500d594ee1c40802c2554cb7f72f87e732d600b7aded5d69478f9ff4a9acebea9bbed85edc35873f

data/README.md

@@ -5,9 +5,9 @@
 ![Coverage](https://didww.github.io/credit_card_validations/badge.svg)
 
 
-Gem adds validator  to check whether or not a given number actually falls within the ranges of possible numbers prior to performing such verification, and, as such, CreditCardValidations simply verifies that the credit card number provided is well-formed.
+Gem adds a validator to check whether a given number actually falls within the ranges of possible numbers prior to performing verification — `CreditCardValidations` verifies that the credit card number provided is well-formed.
 
-More info about card BIN numbers http://en.wikipedia.org/wiki/Bank_card_number
+More info about card BIN numbers: http://en.wikipedia.org/wiki/Bank_card_number
 
 ## Installation
 
@@ -29,158 +29,250 @@ Or install it yourself as:
 $ gem install credit_card_validations
 ```
 
-## Usage
+## Default brands
 
+These brands are detected out of the box. They are the international majors that most acquirers, gateways, and payment forms care about:
 
-The following issuing institutes are accepted:
-    
-|    Name   |    Key     | 
----------------------   | ------------| 
-[American Express](http://en.wikipedia.org/wiki/American_Express) | :amex
-[China UnionPay](http://en.wikipedia.org/wiki/China_UnionPay)    | :unionpay 
-[Dankort](http://en.wikipedia.org/wiki/Dankort)      | :dankort
-[Diners Club](http://en.wikipedia.org/wiki/Diners_Club_International)  | :diners   
-[Elo](https://pt.wikipedia.org/wiki/Elo_Participa%C3%A7%C3%B5es_S/A)      | :elo
-[Discover](http://en.wikipedia.org/wiki/Discover_Card) | :discover   
-[Hipercard](http://pt.wikipedia.org/wiki/Hipercard) | :hipercard  
-[JCB](http://en.wikipedia.org/wiki/Japan_Credit_Bureau)  | :jcb
-[Maestro](http://en.wikipedia.org/wiki/Maestro_%28debit_card%29)    | :maestro
-[MasterCard](http://en.wikipedia.org/wiki/MasterCard)  |   :mastercard
-[MIR](http://www.nspk.ru/en/cards-mir/)  |   :mir
-[Rupay](http://en.wikipedia.org/wiki/RuPay) |   :rupay 
-[Solo](http://en.wikipedia.org/wiki/Solo_(debit_card))     | :solo
-[Switch](http://en.wikipedia.org/wiki/Switch_(debit_card)) | :switch 
-[Visa](http://en.wikipedia.org/wiki/Visa_Inc.)      | :visa  
+|    Name   |    Key     |
+---------------------   | ------------|
+[American Express](http://en.wikipedia.org/wiki/American_Express) | `:amex`
+[China UnionPay](http://en.wikipedia.org/wiki/China_UnionPay) | `:unionpay`
+[Diners Club](http://en.wikipedia.org/wiki/Diners_Club_International) | `:diners`
+[Discover](http://en.wikipedia.org/wiki/Discover_Card) | `:discover`
+[JCB](http://en.wikipedia.org/wiki/Japan_Credit_Bureau) | `:jcb`
+[Maestro](http://en.wikipedia.org/wiki/Maestro_%28debit_card%29) | `:maestro`
+[MasterCard](http://en.wikipedia.org/wiki/MasterCard) | `:mastercard`
+[Visa](http://en.wikipedia.org/wiki/Visa_Inc.) | `:visa`
 
+## Opt-in plugins
 
+Everything else is detected only when its plugin is explicitly required. Plugins add no startup cost, no API surface, and no chance of misdetection to apps that don't accept the brand.
 
-The following are supported with plugins
+### Active regional and specialty networks
 
 |    Name   |    Key     |
 ---------------------   | ------------|
-[Cabal](https://en.wikipedia.org/wiki/Cabal_(debit_card)) | :cabal
-[DinaCard](https://en.wikipedia.org/wiki/DinaCard) | :dinacard
-[Diners Club US](http://en.wikipedia.org/wiki/Diners_Club_International#MasterCard_alliance)  | :diners_us
-[EnRoute](https://en.wikipedia.org/wiki/EnRoute_(credit_card)) | :en_route
-[Girocard](https://en.wikipedia.org/wiki/Girocard) | :girocard
-[Hiper](https://en.wikipedia.org/wiki/Itau_Unibanco) | :hiper
-[Humo](https://en.wikipedia.org/wiki/Humo_(payment_system)) | :humocard
-[Laser](https://en.wikipedia.org/wiki/Laser_%28debit_card%29)      | :laser
-[Troy](https://en.wikipedia.org/wiki/Troy_(payment_system)) | :troy
-[UATP](https://en.wikipedia.org/wiki/Universal_Air_Travel_Plan) | :uatp
-[Uzcard](https://en.wikipedia.org/wiki/Uzcard) | :uzcard
-[V Pay](https://en.wikipedia.org/wiki/V_Pay) | :vpay
-[Verve](https://en.wikipedia.org/wiki/Verve_(payment_card)) | :verve
-[Voyager](https://en.wikipedia.org/wiki/Voyager_card) | :voyager
+[Cabal](https://en.wikipedia.org/wiki/Cabal_(debit_card)) | `:cabal`
+[Carnet](https://en.wikipedia.org/wiki/Carnet_(card)) | `:carnet`
+[Cartes Bancaires](https://en.wikipedia.org/wiki/Cartes_Bancaires) | `:cartes_bancaires`
+[Dankort](http://en.wikipedia.org/wiki/Dankort) | `:dankort`
+[DinaCard](https://en.wikipedia.org/wiki/DinaCard) | `:dinacard`
+[Elo](https://pt.wikipedia.org/wiki/Elo_Participa%C3%A7%C3%B5es_S/A) | `:elo`
+[Girocard](https://en.wikipedia.org/wiki/Girocard) | `:girocard`
+[Hiper](https://en.wikipedia.org/wiki/Itau_Unibanco) | `:hiper`
+[Hipercard](http://pt.wikipedia.org/wiki/Hipercard) | `:hipercard`
+[Humo](https://en.wikipedia.org/wiki/Humo_(payment_system)) | `:humocard`
+[Mada](https://en.wikipedia.org/wiki/Mada_(payment_system)) | `:mada`
+[MIR](http://www.nspk.ru/en/cards-mir/) | `:mir`
+[Naranja](https://en.wikipedia.org/wiki/Tarjeta_Naranja) | `:naranja`
+[RuPay](http://en.wikipedia.org/wiki/RuPay) | `:rupay`
+[Troy](https://en.wikipedia.org/wiki/Troy_(payment_system)) | `:troy`
+[UATP](https://en.wikipedia.org/wiki/Universal_Air_Travel_Plan) | `:uatp`
+[Uzcard](https://en.wikipedia.org/wiki/Uzcard) | `:uzcard`
+[V Pay](https://en.wikipedia.org/wiki/V_Pay) | `:vpay`
+[Verve](https://en.wikipedia.org/wiki/Verve_(payment_card)) | `:verve`
+[Voyager](https://en.wikipedia.org/wiki/Voyager_card) | `:voyager`
+
+### Legacy / withdrawn networks
+
+|    Name   |    Key     | Status |
+---------------------   | ------------| ------|
+[Diners Club US](http://en.wikipedia.org/wiki/Diners_Club_International#MasterCard_alliance) | `:diners_us` | Merged into Discover for US routing in 2008 |
+[EnRoute](https://en.wikipedia.org/wiki/EnRoute_(credit_card)) | `:en_route` | Withdrawn 1989 |
+[Laser](https://en.wikipedia.org/wiki/Laser_%28debit_card%29) | `:laser` | Withdrawn 2014 |
+[Solo](https://en.wikipedia.org/wiki/Solo_(debit_card)) | `:solo` | Withdrawn 2011 |
+[Switch](https://en.wikipedia.org/wiki/Switch_(debit_card)) | `:switch` | Withdrawn 2002 |
+
+### Loading plugins
+
+```ruby
+# in an initializer or before first use
+require 'credit_card_validations/plugins/mir'
+require 'credit_card_validations/plugins/elo'
+require 'credit_card_validations/plugins/hipercard'
+# ... whichever brands the app actually accepts
+```
+
+## Migrating from v8.x → v9.0
 
+Seven brands moved from the default brand set to opt-in plugins in v9.0. The auto-require shim keeps existing code working for one major version with a one-time deprecation warning per brand.
 
+| Brand | Status | Auto-loaded until |
+|---|---|---|
+| `:dankort` | Active (Denmark) | v10.0 |
+| `:elo` | Active (Brazil) | v10.0 |
+| `:hipercard` | Active (Brazil) | v10.0 |
+| `:mir` | Active (Russia) | v10.0 |
+| `:rupay` | Active (India) | v10.0 |
+| `:solo` | Withdrawn 2011 | v10.0 |
+| `:switch` | Withdrawn 2002 | v10.0 |
 
-### Examples using string monkey patch
+If your code references any of these brands by symbol, add the matching `require` to your initializer to silence the warning and survive v10:
+
+```ruby
+# config/initializers/credit_card_validations.rb
+require 'credit_card_validations/plugins/mir'
+require 'credit_card_validations/plugins/elo'
+# ...
+```
+
+When v10 lands, the auto-load disappears. Code that names these brands without a matching `require` will see them as unknown — `Detector#brand` returns `nil`, predicate methods (`mir?`, `elo?`, …) are not defined, and `valid?(:mir)` returns false.
+
+### Other breaking changes in v9.0
+
+- **`Hipercard` cleaned up.** Length changed from 19 to 16 (which is the issued length); legacy `637*` prefixes that actually belong to Hiper were dropped. If you used Hipercard before, your detection now matches the brand's real spec.
+- **`Discover` cleaned up.** Diners-only prefixes (`300-305, 3095, 36, 38, 39`) were dropped from Discover. Diners cards now correctly detect as `:diners` instead of `:discover`. Apps that branched on `:discover` for routing should branch on `[:diners, :discover]`.
+- **`Luhn.valid?` is now strict.** It accepts a digit-only string and returns `false` for `nil`, empty input, or any non-digit character. User-facing input handling moved into `Detector#initialize`, which strips whitespace and dashes before delegating.
+- **Brand YAML is loaded via `YAML.safe_load_file`.** Custom brand sources may need to declare `permitted_classes: [Symbol]` if they relied on extra Ruby objects.
+
+## Usage
+
+### String monkey patch
 
 ```ruby
 require 'credit_card_validations/string'
-'5274 5763 9425 9961'.credit_card_brand   #=> :mastercard
-'5274 5763 9425 9961'.credit_card_brand_name   #=> "MasterCard"
-'5274 5763 9425 9961'.valid_credit_card_brand?(:mastercard, :visa) #=> true
-'5274 5763 9425 9961'.valid_credit_card_brand?(:amex) #=> false
-'5274 5763 9425 9961'.valid_credit_card_brand?('MasterCard') #=> true
+'5274 5763 9425 9961'.credit_card_brand                                #=> :mastercard
+'5274 5763 9425 9961'.credit_card_brand_name                           #=> "MasterCard"
+'5274 5763 9425 9961'.valid_credit_card_brand?(:mastercard, :visa)     #=> true
+'5274 5763 9425 9961'.valid_credit_card_brand?(:amex)                  #=> false
+'5274 5763 9425 9961'.valid_credit_card_brand?('MasterCard')           #=> true
 ```
 
-### ActiveModel support
+### ActiveModel validators
 
-only for certain brands
+Restrict to a brand list:
 
 ```ruby
 class CreditCardModel
   attr_accessor :number
   include ActiveModel::Validations
-  validates :number, credit_card_number: {brands: [:amex, :maestro]}
+  validates :number, credit_card_number: { brands: [:amex, :maestro] }
 end
 ```
 
-for all known brands
+Accept any known brand:
 
 ```ruby
 validates :number, presence: true, credit_card_number: true
 ```
 
-### Examples using CreditCardValidations::Detector class
+### CVV validator
+
+CVV against a brand pulled from another attribute (the PAN):
 
 ```ruby
-number = "4111111111111111"
-detector = CreditCardValidations::Detector.new(number)
-detector.brand #:visa
-detector.visa? #true
-detector.valid?(:mastercard,:maestro) #false
-detector.valid?(:visa, :mastercard) #true
-detector.issuer_category  #"Banking and financial"
+class Payment
+  include ActiveModel::Validations
+  attr_accessor :card_number, :cvv
+
+  validates :card_number, credit_card_number: true
+  validates :cvv,         credit_card_cvv: { brand_from: :card_number }
+end
 ```
 
-### Also You can add your own brand rules to detect other credit card brands/types
-passing name,length(integer/array of integers) and prefix(string/array of strings)
-Example
+CVV against a literal brand:
 
 ```ruby
-CreditCardValidations.add_brand(:voyager, {length: 15, prefixes: '86'})
-voyager_test_card_number = '869926275400212'
-CreditCardValidations::Detector.new(voyager_test_card_number).brand #:voyager
-CreditCardValidations::Detector.new(voyager_test_card_number).voyager? #true
+validates :cvv, credit_card_cvv: { brand: :amex }
 ```
 
-### Remove brands also supported
+### Expiration validator
+
+A single string attribute (`MM/YY`, `MM/YYYY`, `MMYY`, ...):
 
 ```ruby
-CreditCardValidations::Detector.delete_brand(:maestro)
+validates :expiration, credit_card_expiration: true
 ```
 
-### Check luhn
+Two separate fields (typical month + year dropdowns) — use the `Expiration` class in a `validate` block:
 
 ```ruby
-CreditCardValidations::Detector.new(@credit_card_number).valid_luhn?
-#or
-CreditCardValidations::Luhn.valid?(@credit_card_number)
+class Payment
+  attr_accessor :exp_month, :exp_year
+
+  validate do
+    exp = CreditCardValidations::Expiration.new(exp_month, exp_year)
+    errors.add(:exp_month, :invalid) unless exp.valid?
+  end
+end
 ```
 
-### Generate credit card numbers that pass validation
+### `CreditCardValidations::Card`
+
+A composite model wrapping `Detector` and `Expiration` behind a single ActiveModel-aware object:
 
 ```ruby
-CreditCardValidations::Factory.random(:amex)
-# => "348051773827666"
-CreditCardValidations::Factory.random(:maestro)
-# => "6010430241237266856"
+card = CreditCardValidations::Card.new(
+  number: '4111 1111 1111 1111',
+  month: 12, year: 2027,
+  verification_value: '123',
+  name: 'John Smith'
+)
+card.valid?            # => true
+card.brand             # => :visa
+card.display_number    # => "************1111"
+card.last_digits       # => "1111"
+card.expired?          # => false
+card.formatted_number  # => "4111 1111 1111 1111"
 ```
 
-### Plugins
+### Using `Detector` directly
 
 ```ruby
-require 'credit_card_validations/plugins/en_route'
-require 'credit_card_validations/plugins/laser'
-require 'credit_card_validations/plugins/diners_us'
+number   = '4111111111111111'
+detector = CreditCardValidations::Detector.new(number)
+
+detector.brand                          # => :visa
+detector.visa?                          # => true
+detector.valid?(:mastercard, :maestro)  # => false
+detector.valid?(:visa, :mastercard)     # => true
+detector.issuer_category                # => "Banking and financial"
+detector.last4                          # => "1111"
+detector.masked                         # => "************1111"
+detector.formatted                      # => "4111 1111 1111 1111"
+detector.possible_brands                # => [:visa]   (during live input)
+detector.valid_cvv?('123')              # => true
+```
+
+### Adding a custom brand at runtime
 
-require 'credit_card_validations/plugins/cabal'
-require 'credit_card_validations/plugins/dinacard'
-require 'credit_card_validations/plugins/girocard'
-require 'credit_card_validations/plugins/hiper'
-require 'credit_card_validations/plugins/humocard'
-require 'credit_card_validations/plugins/troy'
-require 'credit_card_validations/plugins/uatp'
-require 'credit_card_validations/plugins/uzcard'
-require 'credit_card_validations/plugins/verve'
-require 'credit_card_validations/plugins/voyager'
-require 'credit_card_validations/plugins/vpay'
+```ruby
+CreditCardValidations.add_brand(:voyager, { length: 15, prefixes: '86' })
+CreditCardValidations::Detector.new('869926275400212').voyager?  # => true
 ```
 
+### Removing a brand at runtime
 
-### Configuration
+```ruby
+CreditCardValidations::Detector.delete_brand(:maestro)
+```
 
-In order to override default data source you can copy [original one](https://github.com/didww/credit_card_validations/blob/master/lib/data/brands.yaml) , change it and configure during rails initializer
+### Luhn check
 
 ```ruby
- CreditCardValidations.configure do |config|
-      config.source = '/path/to/my_brands.yml'
- end
+CreditCardValidations::Detector.new(number).valid_luhn?
+# or, on a clean digit string:
+CreditCardValidations::Luhn.valid?(number)
 ```
 
+### Generating Luhn-valid test numbers
+
+```ruby
+CreditCardValidations::Factory.random(:amex)
+# => "348051773827666"
+CreditCardValidations::Factory.random(:maestro)
+# => "6010430241237266856"
+```
+
+## Configuration
+
+To override the default brand source, copy [the bundled `brands.yaml`](https://github.com/didww/credit_card_validations/blob/master/lib/data/brands.yaml), edit it, and point the gem at it in a Rails initializer:
+
+```ruby
+CreditCardValidations.configure do |config|
+  config.source = '/path/to/my_brands.yml'
+end
+```
 
 ## Contributing
 
@@ -188,7 +280,4 @@ In order to override default data source you can copy [original one](https://git
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
-
-
-
+5. Open a Pull Request

data/lib/active_model/credit_card_cvv_validator.rb

@@ -0,0 +1,35 @@
+# == ActiveModel CreditCardCvvValidator
+#
+# Validates a card verification value (CVV / CVC / CID) against either a
+# brand passed explicitly, or a brand derived from another attribute.
+#
+#   class Payment
+#     include ActiveModel::Validations
+#     attr_accessor :card_number, :cvv
+#
+#     validates :cvv, credit_card_cvv: { brand_from: :card_number }
+#   end
+#
+#   class Payment
+#     validates :cvv, credit_card_cvv: { brand: :amex }
+#   end
+#
+module ActiveModel
+  module Validations
+    class CreditCardCvvValidator < EachValidator
+      def validate_each(record, attribute, value)
+        brand = resolve_brand(record)
+        return if brand && CreditCardValidations::Detector.valid_cvv?(value, brand)
+        record.errors.add(attribute, options[:message] || :invalid)
+      end
+
+      private
+
+      def resolve_brand(record)
+        return options[:brand] if options[:brand]
+        pan = record.public_send(options[:brand_from]).to_s if options[:brand_from]
+        CreditCardValidations::Detector.new(pan).brand if pan
+      end
+    end
+  end
+end

data/lib/active_model/credit_card_expiration_validator.rb

@@ -0,0 +1,26 @@
+# == ActiveModel CreditCardExpirationValidator
+#
+# Validates a card expiration date held in a single attribute as a parseable
+# string (MM/YY, MM/YYYY, MMYY, ...).
+#
+#   class Payment
+#     include ActiveModel::Validations
+#     attr_accessor :expiration
+#
+#     validates :expiration, credit_card_expiration: true
+#   end
+#
+# For forms with separate month + year fields, use the Expiration class
+# directly in a plain validate block (see README).
+#
+module ActiveModel
+  module Validations
+    class CreditCardExpirationValidator < EachValidator
+      def validate_each(record, attribute, value)
+        expiration = CreditCardValidations::Expiration.parse(value)
+        return if expiration && expiration.valid?
+        record.errors.add(attribute, options[:message] || :invalid)
+      end
+    end
+  end
+end

data/lib/credit_card_validations/card.rb

@@ -0,0 +1,61 @@
+require 'active_model'
+
+# == CreditCardValidations::Card
+#
+# Slim alternative to ActiveMerchant::Billing::CreditCard for the validation
+# use case. Wraps PAN, expiration, verification value and cardholder name
+# behind a single ActiveModel-aware object.
+#
+#   card = CreditCardValidations::Card.new(
+#     number: '4111 1111 1111 1111',
+#     month: 12, year: 2027,
+#     verification_value: '123',
+#     name: 'John Smith'
+#   )
+#   card.valid?            # => true
+#   card.brand             # => :visa
+#   card.display_number    # => "************1111"
+#   card.last_digits       # => "1111"
+#   card.expired?          # => false
+#   card.formatted_number  # => "4111 1111 1111 1111"
+#
+module CreditCardValidations
+  class Card
+    include ActiveModel::Model
+
+    attr_accessor :number, :month, :year, :verification_value, :name
+
+    validates :number, credit_card_number: true
+    validates :verification_value, credit_card_cvv: { brand_from: :number }
+    validate :expiration_must_be_valid
+
+    def brand              = detector.brand
+    def brand_name         = detector.brand_name
+    def last_digits        = detector.last4
+    def display_number     = detector.masked
+    def formatted_number   = detector.formatted
+
+    def expiration
+      return nil unless month && year
+      Expiration.new(month, year)
+    end
+
+    def expired?
+      exp = expiration
+      exp.nil? || exp.expired?
+    end
+
+    def detector
+      @detector ||= Detector.new(number)
+    end
+
+    private
+
+    def expiration_must_be_valid
+      return if month.blank? && year.blank?
+      exp = expiration
+      errors.add(:base, :expired) if exp && exp.expired?
+      errors.add(:month, :invalid) if exp && !(1..12).cover?(exp.month)
+    end
+  end
+end

data/lib/credit_card_validations/detector.rb

@@ -9,10 +9,17 @@ module CreditCardValidations
     class_attribute :brands
     self.brands = {}
 
+    # Brands that were part of the default set up to v8.x and moved to
+    # opt-in plugins in v9.0. The shim below auto-loads the plugin on first
+    # reference and emits a one-time deprecation warning. To be removed in
+    # v10.0 — users should add explicit `require` statements by then.
+    LEGACY_PLUGIN_BRANDS = %i[mir rupay elo dankort hipercard solo switch].freeze
+    @@legacy_autoloaded = {}
+
     attr_reader :number
 
     def initialize(number)
-      @number = number.to_s.tr('- ', '')
+      @number = number.to_s.gsub(/[\s\-]/, '')
     end
 
     # credit card number validation
@@ -50,8 +57,62 @@ module CreditCardValidations
       self.class.brand_name(brand)
     end
 
+    # Last four digits of the PAN, or nil if the PAN has fewer than 4 digits.
+    def last4
+      number.length >= 4 ? number[-4, 4] : nil
+    end
+
+    # PAN with every digit but the last 4 replaced by mask_char.
+    # Returns the original number when shorter than 4 digits — never raises.
+    def masked(mask_char = '*')
+      return number if number.length < 4
+      mask_char.to_s[0] * (number.length - 4) + last4.to_s
+    end
+
+    # All brands whose prefixes can still match the (possibly partial) PAN.
+    # Length and Luhn are not checked — useful for live UX before the user
+    # finishes typing.
+    def possible_brands
+      return [] if number.empty?
+      self.class.brands.each_with_object([]) do |(key, brand), acc|
+        next unless brand.fetch(:rules).any? do |rule|
+          rule[:prefixes].any? do |prefix|
+            n = [number.length, prefix.length].min
+            number[0, n] == prefix[0, n]
+          end
+        end
+        acc << key
+      end
+    end
+
+    # Human-readable PAN grouped per network convention. Falls back to the
+    # first possible brand while the user is still typing.
+    def formatted(separator = ' ')
+      groups_for(brand || possible_brands.first).each_with_object([]) do |size, acc|
+        slice = number[acc.join.length, size]
+        acc << slice if slice && !slice.empty?
+      end.join(separator)
+    end
+
+    # Validates the card verification value against the detected brand's
+    # declared :code size. Returns false when the brand cannot be determined
+    # from the PAN or the input has the wrong shape. Raises when a detected
+    # brand is missing :code in the registry.
+    def valid_cvv?(code)
+      self.class.valid_cvv?(code, brand)
+    end
+
     protected
 
+    def groups_for(detected_brand)
+      segments = self.class.brands.dig(detected_brand, :options, :segments)
+      return segments if segments
+      groups = Array.new(number.length / 4, 4)
+      remainder = number.length % 4
+      groups << remainder if remainder.positive?
+      groups
+    end
+
     def resolve_keys(*keys)
       brand_keys = keys.map do |el|
         if el.is_a? String
@@ -60,9 +121,25 @@ module CreditCardValidations
         end
         el.downcase
       end
+      brand_keys.each { |k| autoload_legacy_plugin(k) }
       self.brands.slice(*brand_keys)
     end
 
+    def autoload_legacy_plugin(key)
+      return unless LEGACY_PLUGIN_BRANDS.include?(key)
+      return if self.class.brands.key?(key)
+      return if @@legacy_autoloaded[key]
+      @@legacy_autoloaded[key] = true
+
+      Warning.warn(
+        "[credit_card_validations] :#{key} was moved to a plugin in v9.0. " \
+        "Auto-loading 'credit_card_validations/plugins/#{key}' for backward " \
+        "compatibility. Add `require 'credit_card_validations/plugins/#{key}'` " \
+        "to your initializer to silence; auto-load is removed in v10.\n"
+      )
+      load "credit_card_validations/plugins/#{key}.rb"
+    end
+
     def matches_brand?(brand)
       rules = brand.fetch(:rules)
       options = brand.fetch(:options, {})
@@ -83,12 +160,26 @@ module CreditCardValidations
         !brands[key].fetch(:options, {}).fetch(:skip_luhn, false)
       end
 
+      # Class-level CVV check: validates a code against an explicit brand,
+      # without needing a Detector instance. Useful when only the brand is
+      # known (form input bound to a brand select, separate CVV field, etc.).
+      def valid_cvv?(code, brand)
+        return false if code.nil? || brand.nil? || !code.to_s.match?(/\A\d+\z/)
+        spec = brands.dig(brand, :options, :code)
+        raise Error, "brand #{brand.inspect} has no :code option" if spec.nil?
+        code.to_s.length == spec[:size]
+      end
+
       #
       # add brand
       #
       #   CreditCardValidations.add_brand(:en_route, {length: 15, prefixes: ['2014', '2149']}, {skip_luhn: true}) #skip luhn
       #
       def add_brand(key, rules, options = {})
+        # Mark legacy plugin brands as handled so the v9 auto-require shim
+        # never re-loads them after the user takes any explicit action
+        # (require, add_brand, or a later delete_brand).
+        @@legacy_autoloaded[key] = true if LEGACY_PLUGIN_BRANDS.include?(key)
 
         brands[key] = {rules: [], options: options || {}}