creditcard-identifier 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2971d1554919d8eaf0fd916f87d9003cee3aae39d07e0b6f6de388d19eff31f1
+  data.tar.gz: c51129f59758f48b10b24f1e7f7f2d6ee336b62aa8e91fceed7ead69d1005fcb
+SHA512:
+  metadata.gz: 0b831eb2196ceab513b4b2e77907abd454d14cfb13052dc0e14eea01ad964bfff247f13fdfb382bb0f9bb210c0409721853f02e414a6c05cf6dea8c87c030df0
+  data.tar.gz: 10f73f531f751c2f48f347daed4b1d2f726cd19495ae579d4a80b6d40e5b4ea6a2f8b694f17f80d6d46bb8327a1530a936743e86382b5453d92de98ab3559e6e

data/README.md

@@ -0,0 +1,153 @@
+# Credit Card Identifier - Ruby Library
+
+Ruby library for credit card BIN validation using bin-cc data.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'creditcard-identifier'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install creditcard-identifier
+```
+
+## Usage
+
+### Module-level Functions
+
+```ruby
+require 'creditcard_identifier'
+
+# Identify card brand
+brand = CreditcardIdentifier.find_brand('4012001037141112')
+puts brand  # 'visa'
+
+# Check if card is supported
+supported = CreditcardIdentifier.supported?('4012001037141112')
+puts supported  # true
+```
+
+### Using the Validator Class
+
+```ruby
+require 'creditcard_identifier'
+
+validator = CreditcardIdentifier::Validator.new
+
+# Identify brand
+brand = validator.find_brand('4012001037141112')
+puts brand  # 'visa'
+
+# Check if supported
+supported = validator.supported?('4012001037141112')
+puts supported  # true
+
+# Validate CVV
+valid = validator.validate_cvv('123', 'visa')
+puts valid  # true
+
+# Get brand info
+info = validator.get_brand_info('visa')
+puts info['regexpBin']
+
+# List all brands
+brands = validator.list_brands
+puts brands  # ['elo', 'diners', 'visa', ...]
+```
+
+## API
+
+### Module Methods
+
+#### `CreditcardIdentifier.find_brand(card_number)`
+Identify the credit card brand.
+
+**Parameters:**
+- `card_number` (String): The credit card number
+
+**Returns:** (String, nil) Brand name (e.g., 'visa', 'mastercard') or nil if not found
+
+#### `CreditcardIdentifier.supported?(card_number)`
+Check if the card number is supported.
+
+**Parameters:**
+- `card_number` (String): The credit card number
+
+**Returns:** (Boolean) true if supported, false otherwise
+
+### Validator Class
+
+#### `initialize(data_path = nil)`
+Initialize validator with brand data.
+
+**Parameters:**
+- `data_path` (String, nil): Path to brands.json. If nil, uses bundled data.
+
+#### `find_brand(card_number)`
+Identify the credit card brand.
+
+**Parameters:**
+- `card_number` (String): The credit card number
+
+**Returns:** (String, nil) Brand name or nil if not found
+
+#### `supported?(card_number)`
+Check if card number is supported.
+
+**Parameters:**
+- `card_number` (String): The credit card number
+
+**Returns:** (Boolean) true if supported, false otherwise
+
+#### `validate_cvv(cvv, brand_name)`
+Validate CVV for a specific brand.
+
+**Parameters:**
+- `cvv` (String): CVV code
+- `brand_name` (String): Brand name (e.g., 'visa', 'mastercard')
+
+**Returns:** (Boolean) true if valid, false otherwise
+
+#### `get_brand_info(brand_name)`
+Get information about a specific brand.
+
+**Parameters:**
+- `brand_name` (String): Brand name
+
+**Returns:** (Hash, nil) Brand information or nil if not found
+
+#### `list_brands`
+List all supported brands.
+
+**Returns:** (Array<String>) List of brand names
+
+## Data Source
+
+This library uses the BIN data from the [bin-cc project](https://github.com/renatovico/bin-cc).
+
+The data is bundled with the gem, and can be updated by installing a newer version.
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies.
+
+Run tests with:
+
+```bash
+ruby test/test_validator.rb
+```
+
+## License
+
+MIT

data/lib/creditcard_identifier/brands.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Auto-generated by bin-cc build - DO NOT EDIT
+# Generated: 2026-01-11T20:12:36.612Z
+
+module CreditcardIdentifier
+  # Credit card brand data
+  BRANDS = [
+    {
+      name: "amex",
+      priority_over: [],
+      regexp_bin: /\A(3[47])/,
+      regexp_full: /\A(?=.{15}$)(?:3[47])[0-9]*\z/,
+      regexp_cvv: /\A\d{4}\z/,
+    },
+    {
+      name: "diners",
+      priority_over: [],
+      regexp_bin: /\A(3(?:0[0-5]|[68][0-9]))/,
+      regexp_full: /\A(?=.{14}$)(?:3(?:0[0-5]|[68][0-9]))[0-9]*\z/,
+      regexp_cvv: /\A\d{3}\z/,
+    },
+    {
+      name: "elo",
+      priority_over: ["visa", "aura", "discover", "banesecard"],
+      regexp_bin: /\A(401178|401179|431274|438935|451416|457393|457631|457632|504175|627780|636297|636368|(506699|5067[0-6]\d|50677[0-8])|(50900\d|5090[1-9]\d|509[1-9]\d{2})|65003[1-3]|(65003[5-9]|65004\d|65005[0-1])|(65040[5-9]|6504[1-3]\d)|(65048[5-9]|65049\d|6505[0-2]\d|65053[0-8])|(65054[1-9]|6505[5-8]\d|65059[0-8])|(65070\d|65071[0-8])|6507(2[0-7])|6509[0-9]|(65165[2-9]|6516[6-7]\d)|(65500\d|65501\d)|(65502[1-9]|6550[3-4]\d|65505[0-8]))/,
+      regexp_full: /\A(?=.{16}$)(?:401178|401179|431274|438935|451416|457393|457631|457632|504175|627780|636297|636368|(506699|5067[0-6]\d|50677[0-8])|(50900\d|5090[1-9]\d|509[1-9]\d{2})|65003[1-3]|(65003[5-9]|65004\d|65005[0-1])|(65040[5-9]|6504[1-3]\d)|(65048[5-9]|65049\d|6505[0-2]\d|65053[0-8])|(65054[1-9]|6505[5-8]\d|65059[0-8])|(65070\d|65071[0-8])|6507(2[0-7])|6509[0-9]|(65165[2-9]|6516[6-7]\d)|(65500\d|65501\d)|(65502[1-9]|6550[3-4]\d|65505[0-8]))[0-9]*\z/,
+      regexp_cvv: /\A\d{3}\z/,
+    },
+    {
+      name: "jcb",
+      priority_over: [],
+      regexp_bin: /\A((?:2131|1800|35))/,
+      regexp_full: /\A(?=.{16}$)(?:(?:2131|1800|35))[0-9]*\z/,
+      regexp_cvv: /\A\d{3}\z/,
+    },
+    {
+      name: "mastercard",
+      priority_over: [],
+      regexp_bin: /\A(5[1-5]|2[2-7][0-2][0-9])/,
+      regexp_full: /\A(?=.{16}$)(?:5[1-5]|2[2-7][0-2][0-9])[0-9]*\z/,
+      regexp_cvv: /\A\d{3}\z/,
+    },
+    {
+      name: "aura",
+      priority_over: [],
+      regexp_bin: /\A(50)/,
+      regexp_full: /\A(?=.{16,19}$)(?:50)[0-9]*\z/,
+      regexp_cvv: /\A\d{3}\z/,
+    },
+    {
+      name: "banesecard",
+      priority_over: ["discover"],
+      regexp_bin: /\A(636117|637473|637470|637472|650725|650046|650591|651668|651679)/,
+      regexp_full: /\A(?=.{16}$)(?:636117|637473|637470|637472|650725|650046|650591|651668|651679)[0-9]*\z/,
+      regexp_cvv: /\A\d{3}\z/,
+    },
+    {
+      name: "visa",
+      priority_over: [],
+      regexp_bin: /\A(4|6367)/,
+      regexp_full: /\A(?=.{13,16}$)(?:4|6367)[0-9]*\z/,
+      regexp_cvv: /\A\d{3}\z/,
+    },
+    {
+      name: "discover",
+      priority_over: ["hipercard"],
+      regexp_bin: /\A(6011|622|64|65)/,
+      regexp_full: /\A(?=.{16}$)(?:6011|622|64|65)[0-9]*\z/,
+      regexp_cvv: /\A\d{4}\z/,
+    },
+    {
+      name: "hipercard",
+      priority_over: [],
+      regexp_bin: /\A(38|60)/,
+      regexp_full: /\A(?=.{16,19}$)(?:38|60)[0-9]*\z/,
+      regexp_cvv: /\A\d{3}\z/,
+    },
+  ].freeze
+end

data/lib/creditcard_identifier/brands_detailed.rb

@@ -0,0 +1,524 @@
+# frozen_string_literal: true
+
+# Auto-generated by bin-cc build - DO NOT EDIT
+# Generated: 2026-01-11T20:12:36.612Z
+
+module CreditcardIdentifier
+  # Credit card brand data (detailed)
+  BRANDS_DETAILED = [
+    {
+      scheme: "amex",
+      brand: "American Express",
+      type: "credit",
+      number: {
+        lengths: [15],
+        luhn: true
+      },
+      cvv: {
+        length: 4
+      },
+      patterns: [
+        {
+          bin: "^3[47]",
+          length: [15],
+          luhn: true,
+          cvv_length: 4
+        },
+      ],
+      countries: ["GLOBAL"],
+      metadata: { "sourceFile" => "amex.json" },
+      priority_over: [],
+      bins: []
+    },
+    {
+      scheme: "diners",
+      brand: "Diners Club",
+      type: "credit",
+      number: {
+        lengths: [14],
+        luhn: true
+      },
+      cvv: {
+        length: 3
+      },
+      patterns: [
+        {
+          bin: "^3(?:0[0-5]|[68][0-9])",
+          length: [14],
+          luhn: true,
+          cvv_length: 3
+        },
+      ],
+      countries: ["GLOBAL"],
+      metadata: { "sourceFile" => "diners.json" },
+      priority_over: [],
+      bins: []
+    },
+    {
+      scheme: "elo",
+      brand: "Elo",
+      type: "credit",
+      number: {
+        lengths: [16],
+        luhn: true
+      },
+      cvv: {
+        length: 3
+      },
+      patterns: [
+        {
+          bin: "^401178|^401179|^431274|^438935|^451416|^457393|^457631|^457632|^504175",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^627780|^636297|^636368",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^(506699|5067[0-6]\\d|50677[0-8])",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^(50900\\d|5090[1-9]\\d|509[1-9]\\d{2})",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^65003[1-3]",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^(65003[5-9]|65004\\d|65005[0-1])",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^(65040[5-9]|6504[1-3]\\d)",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^(65048[5-9]|65049\\d|6505[0-2]\\d|65053[0-8])",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^(65054[1-9]|6505[5-8]\\d|65059[0-8])",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^(65070\\d|65071[0-8])",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^6507(2[0-7])",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^6509[0-9]",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^(65165[2-9]|6516[6-7]\\d)",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^(65500\\d|65501\\d)",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^(65502[1-9]|6550[3-4]\\d|65505[0-8])",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+      ],
+      countries: ["BR"],
+      metadata: { "sourceFile" => "elo.json" },
+      priority_over: ["visa", "aura", "discover", "banesecard"],
+      bins: []
+    },
+    {
+      scheme: "jcb",
+      brand: "JCB",
+      type: "credit",
+      number: {
+        lengths: [16],
+        luhn: true
+      },
+      cvv: {
+        length: 3
+      },
+      patterns: [
+        {
+          bin: "^(?:2131|1800|35)",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+      ],
+      countries: ["GLOBAL"],
+      metadata: { "sourceFile" => "jcb.json" },
+      priority_over: [],
+      bins: []
+    },
+    {
+      scheme: "mastercard",
+      brand: "Mastercard",
+      type: "credit",
+      number: {
+        lengths: [16],
+        luhn: true
+      },
+      cvv: {
+        length: 3
+      },
+      patterns: [
+        {
+          bin: "^5[1-5]",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^2[2-7][0-2][0-9]",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+      ],
+      countries: ["GLOBAL"],
+      metadata: { "sourceFile" => "mastercard.json" },
+      priority_over: [],
+      bins: []
+    },
+    {
+      scheme: "aura",
+      brand: "Aura",
+      type: "credit",
+      number: {
+        lengths: [16, 17, 18, 19],
+        luhn: true
+      },
+      cvv: {
+        length: 3
+      },
+      patterns: [
+        {
+          bin: "^50",
+          length: [16, 17, 18, 19],
+          luhn: true,
+          cvv_length: 3
+        },
+      ],
+      countries: ["BR"],
+      metadata: { "sourceFile" => "aura.json" },
+      priority_over: [],
+      bins: []
+    },
+    {
+      scheme: "banesecard",
+      brand: "BaneseCard",
+      type: "credit",
+      number: {
+        lengths: [16],
+        luhn: true
+      },
+      cvv: {
+        length: 3
+      },
+      patterns: [
+        {
+          bin: "^636117",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^637473",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^637470",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^637472",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^650725",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^650046",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^650591",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^651668",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^651679",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+      ],
+      countries: ["BR"],
+      metadata: { "sourceFile" => "banesecard.json" },
+      priority_over: ["discover"],
+      bins: []
+    },
+    {
+      scheme: "visa",
+      brand: "Visa",
+      type: "credit",
+      number: {
+        lengths: [13, 16],
+        luhn: true
+      },
+      cvv: {
+        length: 3
+      },
+      patterns: [
+        {
+          bin: "^4",
+          length: [13, 16],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^6367",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+      ],
+      countries: ["GLOBAL"],
+      metadata: { "sourceFile" => ["visa/base.json", "visa/bins-br-1.json", "visa/bins-br-2.json"] },
+      priority_over: [],
+      bins: [
+        {
+          bin: "491441",
+          type: "CREDIT",
+          category: nil,
+          issuer: "BANCO PROSPER, S.A.",
+          countries: ["BR"]
+        },
+        {
+          bin: "491440",
+          type: "CREDIT",
+          category: nil,
+          issuer: "BANCO PROSPER, S.A.",
+          countries: ["BR"]
+        },
+        {
+          bin: "491439",
+          type: "CREDIT",
+          category: nil,
+          issuer: "BANCO PROSPER, S.A.",
+          countries: ["BR"]
+        },
+        {
+          bin: "491423",
+          type: "CREDIT",
+          category: nil,
+          issuer: "BANCO DO ESTADO DO RIO GRANDE DO SUL S.A. (BANRISUL S.A.)",
+          countries: ["BR"]
+        },
+        {
+          bin: "491416",
+          type: "CREDIT",
+          category: "CLASSIC",
+          issuer: "BANCO DO ESTADO DO PARANA",
+          countries: ["BR"]
+        },
+        {
+          bin: "491415",
+          type: "CREDIT",
+          category: "CLASSIC",
+          issuer: "BANCO DO ESTADO DO PARANA",
+          countries: ["BR"]
+        },
+        {
+          bin: "491414",
+          type: "CREDIT",
+          category: "GOLD",
+          issuer: "BANCO DO ESTADO DO PARANA",
+          countries: ["BR"]
+        },
+        {
+          bin: "491413",
+          type: "CREDIT",
+          category: "CLASSIC",
+          issuer: "BANCO DO ESTADO DO RIO GRANDE DO SUL S/A",
+          countries: ["BR"]
+        },
+        {
+          bin: "491412",
+          type: "CREDIT",
+          category: "CLASSIC",
+          issuer: "BANCO DO ESTADO DO RIO GRANDE DO SUL S/A",
+          countries: []
+        },
+        {
+          bin: "491411",
+          type: "CREDIT",
+          category: "GOLD",
+          issuer: "BANCO DO ESTADO DO RIO GRANDE DO SUL S/A",
+          countries: []
+        },
+        {
+          bin: "491402",
+          type: "CREDIT",
+          category: nil,
+          issuer: "BANCO DO ESTADO DO RIO GRANDE DO SUL S.A. (BANRISUL S.A.)",
+          countries: []
+        },
+        {
+          bin: "491316",
+          type: "CREDIT",
+          category: "CLASSIC",
+          issuer: "BANCO SANTANDER BRASIL, S.A.",
+          countries: []
+        },
+        {
+          bin: "491315",
+          type: "CREDIT",
+          category: "CLASSIC",
+          issuer: "BANCO SANTANDER, S.A.",
+          countries: []
+        },
+        {
+          bin: "491314",
+          type: "CREDIT",
+          category: "GOLD",
+          issuer: "BANCO SANTANDER, S.A.",
+          countries: []
+        },
+        {
+          bin: "491256",
+          type: "CREDIT",
+          category: "PLATINUM",
+          issuer: "BANCO PANAMERICANO, S.A.",
+          countries: []
+        },
+      ]
+    },
+    {
+      scheme: "discover",
+      brand: "Discover",
+      type: "credit",
+      number: {
+        lengths: [16],
+        luhn: true
+      },
+      cvv: {
+        length: 4
+      },
+      patterns: [
+        {
+          bin: "^6011",
+          length: [16],
+          luhn: true,
+          cvv_length: 4
+        },
+        {
+          bin: "^622",
+          length: [16],
+          luhn: true,
+          cvv_length: 4
+        },
+        {
+          bin: "^64",
+          length: [16],
+          luhn: true,
+          cvv_length: 4
+        },
+        {
+          bin: "^65",
+          length: [16],
+          luhn: true,
+          cvv_length: 4
+        },
+      ],
+      countries: ["US"],
+      metadata: { "sourceFile" => "discover.json" },
+      priority_over: ["hipercard"],
+      bins: []
+    },
+    {
+      scheme: "hipercard",
+      brand: "Hipercard",
+      type: "credit",
+      number: {
+        lengths: [16, 19],
+        luhn: true
+      },
+      cvv: {
+        length: 3
+      },
+      patterns: [
+        {
+          bin: "^38",
+          length: [19],
+          luhn: true,
+          cvv_length: 3
+        },
+        {
+          bin: "^60",
+          length: [16],
+          luhn: true,
+          cvv_length: 3
+        },
+      ],
+      countries: ["BR"],
+      metadata: { "sourceFile" => "hipercard.json" },
+      priority_over: [],
+      bins: []
+    },
+  ].freeze
+end

data/lib/creditcard_identifier.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require_relative 'creditcard_identifier/brands'
+require_relative 'creditcard_identifier/brands_detailed'
+
+##
+# Credit Card BIN Validator
+#
+# This module provides credit card validation using bin-cc data.
+module CreditcardIdentifier
+  VERSION = '2.0.0'
+
+  ##
+  # Credit card validator using bin-cc data.
+  class Validator
+    attr_reader :brands, :brands_detailed
+
+    ##
+    # Initialize validator with brand data
+    def initialize
+      @brands = BRANDS
+      @brands_detailed = BRANDS_DETAILED
+    end
+
+    ##
+    # Identify the credit card brand
+    #
+    # @param card_number [String] Credit card number
+    # @param detailed [Boolean] If true, returns detailed brand info
+    # @return [Hash, nil] Brand hash or nil if not found
+    def find_brand(card_number, detailed: false)
+      return nil if card_number.nil? || card_number.empty?
+
+      brand = @brands.find do |b|
+        b[:regexp_full].match?(card_number)
+      end
+
+      return nil unless brand
+
+      if detailed
+        detailed_brand = @brands_detailed.find { |b| b[:scheme] == brand[:name] }
+        if detailed_brand
+          # Find the specific pattern that matched
+          matched_pattern = detailed_brand[:patterns]&.find do |p|
+            Regexp.new(p[:bin]).match?(card_number)
+          end
+
+          # Find the specific bin that matched (if bins exist)
+          bin_prefix = card_number[0, 6]
+          matched_bin = detailed_brand[:bins]&.find do |b|
+            bin_prefix.start_with?(b[:bin]) || b[:bin] == bin_prefix
+          end
+
+          # Return without the full bins array
+          result = detailed_brand.reject { |k, _| k == :bins }
+          result[:matched_pattern] = matched_pattern
+          result[:matched_bin] = matched_bin
+          return result
+        end
+      end
+
+      brand
+    end
+
+    ##
+    # Check if card number is supported
+    #
+    # @param card_number [String] Credit card number
+    # @return [Boolean] true if supported, false otherwise
+    def supported?(card_number)
+      !find_brand(card_number).nil?
+    end
+
+    ##
+    # Validate CVV for a specific brand
+    #
+    # @param cvv [String] CVV code
+    # @param brand_or_name [String, Hash] Brand name or brand object from find_brand
+    # @return [Boolean] true if valid, false otherwise
+    def validate_cvv(cvv, brand_or_name)
+      return false if cvv.nil? || cvv.empty?
+
+      # Handle brand object (Hash)
+      if brand_or_name.is_a?(Hash)
+        # Handle detailed brand object
+        if brand_or_name[:cvv] && brand_or_name[:cvv][:length]
+          expected_length = brand_or_name[:cvv][:length]
+          return cvv.match?(/^\d{#{expected_length}}$/)
+        end
+        # Handle simplified brand object
+        if brand_or_name[:regexp_cvv]
+          return brand_or_name[:regexp_cvv].match?(cvv)
+        end
+        # Handle brand name from object
+        brand_name = brand_or_name[:name] || brand_or_name[:scheme]
+        if brand_name
+          brand = @brands.find { |b| b[:name] == brand_name }
+          return brand&.dig(:regexp_cvv)&.match?(cvv) || false
+        end
+        return false
+      end
+
+      # Handle brand name (String)
+      brand = @brands.find { |b| b[:name] == brand_or_name }
+      return false if brand.nil?
+
+      brand[:regexp_cvv].match?(cvv)
+    end
+
+    ##
+    # Get information about a specific brand
+    #
+    # @param brand_name [String] Brand name (e.g., 'visa', 'mastercard')
+    # @return [Hash, nil] Brand hash or nil if not found
+    def get_brand_info(brand_name)
+      @brands.find { |b| b[:name] == brand_name }
+    end
+
+    ##
+    # Get detailed information about a specific brand
+    #
+    # @param scheme [String] Scheme name (e.g., 'visa', 'mastercard')
+    # @return [Hash, nil] Detailed brand hash or nil if not found
+    def get_brand_info_detailed(scheme)
+      @brands_detailed.find { |b| b[:scheme] == scheme }
+    end
+
+    ##
+    # List all supported brands
+    #
+    # @return [Array<String>] List of brand names
+    def list_brands
+      @brands.map { |b| b[:name] }
+    end
+  end
+
+  # Module-level convenience methods
+  class << self
+    ##
+    # Get or create the singleton validator instance
+    #
+    # @return [Validator] The validator instance
+    def validator
+      @validator ||= Validator.new
+    end
+
+    ##
+    # Get all brand data
+    #
+    # @return [Array<Hash>] List of brand hashes
+    def brands
+      BRANDS
+    end
+
+    ##
+    # Get all detailed brand data
+    #
+    # @return [Array<Hash>] List of detailed brand hashes
+    def brands_detailed
+      BRANDS_DETAILED
+    end
+
+    ##
+    # Identify the credit card brand
+    #
+    # @param card_number [String] Credit card number
+    # @param detailed [Boolean] If true, returns detailed brand info
+    # @return [Hash, nil] Brand hash or nil if not found
+    def find_brand(card_number, detailed: false)
+      validator.find_brand(card_number, detailed: detailed)
+    end
+
+    ##
+    # Check if card number is supported
+    #
+    # @param card_number [String] Credit card number
+    # @return [Boolean] true if supported, false otherwise
+    def supported?(card_number)
+      validator.supported?(card_number)
+    end
+
+    ##
+    # Validate CVV for a specific brand
+    #
+    # @param cvv [String] CVV code
+    # @param brand_or_name [String, Hash] Brand name or brand object
+    # @return [Boolean] true if valid, false otherwise
+    def validate_cvv(cvv, brand_or_name)
+      validator.validate_cvv(cvv, brand_or_name)
+    end
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: creditcard-identifier
+version: !ruby/object:Gem::Version
+  version: 2.0.0
+platform: ruby
+authors:
+- Renato Viço
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-01-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: A Ruby library for credit card BIN validation and brand identification
+email: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/creditcard_identifier.rb
+- lib/creditcard_identifier/brands.rb
+- lib/creditcard_identifier/brands_detailed.rb
+homepage: https://github.com/renatovico/bin-cc
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/renatovico/bin-cc
+  source_code_uri: https://github.com/renatovico/bin-cc
+  documentation_uri: https://github.com/renatovico/bin-cc/tree/master/libs/ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Credit card BIN validation using bin-cc data
+test_files: []