@juspay/cards-validator

💳 Cards Validator

A comprehensive JS/TS library for validating credit and debit card numbers

✨ Features

🎯 Card Type Detection Automatically detects 12+ major card types including Visa, MasterCard, American Express, Discover, JCB, Maestro, RuPay, UnionPay, and more	✅ Luhn Algorithm Validation Implements the industry-standard Luhn algorithm for card number validation
📏 Length Validation Validates card number length based on card type specifications	🔢 CVV Length Information Provides valid CVV lengths for each detected card type
🎨 Range-based Detection Uses both regex patterns and BIN ranges for accurate card type identification	📘 TypeScript Support Fully typed with comprehensive type definitions
⚡ Zero Dependencies Lightweight library with no external dependencies

💳 Supported Card Types

Click to view all supported card types

🏦 Card Type	🔍 Pattern/Range	📏 Valid Lengths	🔢 CVV Length
🔵 Visa	^4	16	3
🔴 MasterCard	BIN ranges 222100-272099, 510000-559999	16	3
🔵 American Express	^3[47]	15	4
🟠 Discover	^(6011|622...)	16	3
🟢 JCB	^35(2[89]|[3-8][0-9])	16	3
🔴 Maestro	^(5018|5081|...)	12-19	0, 3
🟣 RuPay	BIN ranges	16	3
🔵 UnionPay	^6[0289]|9[0245689]...	16-19	3
⚪ Diners Club	^30[0-5], ^3([689]|09)	14	3
🟢 Laser	^(6304|670[69]|6771)	16-19	3, 4
🔵 Visa Electron	^(4026|417500|...)	16	3
🟠 Sodexo	^(637513)	16	3

📦 Installation

npm install @juspay/cards-validator

Alternative package managers:

# Using Yarn
yarn add @juspay/cards-validator

# Using pnpm
pnpm add @juspay/cards-validator

🚀 Usage

🎯 Basic Usage

import CardValidator from '@juspay/cards-validator';

// Create a new validator instance
const validator = new CardValidator('4111111111111111');

// Get card validation details
const result = validator.getCardDetails();

console.log(result);
// Output:
// {
//   card_type: 'visa',
//   valid: true,
//   luhn_valid: true,
//   length_valid: true,
//   cvv_length: [3],
//   supported_lengths: [16]
// }

🔧 Advanced Usage

import CardValidator, { CardDetails } from '@juspay/cards-validator';

// Validate different card types
const cards = [
  '4111111111111111',    // Visa
  '5555555555554444',    // MasterCard
  '378282246310005',     // American Express
  '6011111111111117',    // Discover
];

cards.forEach(cardNumber => {
  const validator = new CardValidator(cardNumber);
  const result: CardDetails = validator.getCardDetails();

  console.log(`Card: ${cardNumber}`);
  console.log(`Type: ${result.card_type}`);
  console.log(`Valid: ${result.valid}`);
  console.log(`CVV Length: ${result.cvv_length.join(', ')}`);
  console.log('---');
});

🔄 Handling Spaces and Dashes

The library automatically normalizes card numbers by removing spaces and dashes:

const validator1 = new CardValidator('4111 1111 1111 1111');
const validator2 = new CardValidator('4111-1111-1111-1111');
const validator3 = new CardValidator('4111111111111111');

// All three will produce the same result
console.log(validator1.getCardDetails().valid); // true
console.log(validator2.getCardDetails().valid); // true
console.log(validator3.getCardDetails().valid); // true

📚 API Reference

🏗️ CardValidator Class

Constructor

new CardValidator(cardNumber: string)

• cardNumber: The credit card number to validate (string)

Methods

📋 getCardDetails(): CardDetails

Returns a comprehensive validation result object.

📝 Types

📊 CardDetails

interface CardDetails {
  card_type: string;           // Detected card type (e.g., 'visa', 'mastercard', 'amex', 'unknown')
  valid: boolean;              // Overall validity (luhn_valid && length_valid)
  luhn_valid: boolean;         // Whether card passes Luhn algorithm check
  length_valid: boolean;       // Whether card length is valid for detected type
  cvv_length: number[];        // Valid CVV lengths for this card type, e.g., [3] or [3, 4]
  supported_lengths: number[]; // Valid card number lengths, e.g., [16] or [12,13,14,15,16,17,18,19]
}

💳 CardType

interface CardType {
  name: string;
  valid_length: number[];
  cvv_length: number[];
  pattern?: RegExp;      // For pattern-based detection
  range?: number[][];    // For BIN range-based detection
  gaps?: number[];       // Optional: for formatting (e.g., Sodexo)
}

💡 Examples

🎨 Validate and Format Card Information

import CardValidator from '@juspay/cards-validator';

function formatCardInfo(cardNumber: string) {
  const validator = new CardValidator(cardNumber);
  const result = validator.getCardDetails();

  if (result.valid) {
    return {
      isValid: true,
      cardType: result.card_type.replace('_', ' ').toUpperCase(),
      cvvLength: result.cvv_length,
      message: `Valid ${result.card_type} card`
    };
  } else {
    return {
      isValid: false,
      cardType: result.card_type,
      issues: [
        !result.luhn_valid && 'Invalid checksum',
        !result.length_valid && 'Invalid length'
      ].filter(Boolean),
      message: 'Invalid card number'
    };
  }
}

// Examples
console.log(formatCardInfo('4111111111111111'));
// { isValid: true, cardType: 'VISA', cvvLength: [3], message: 'Valid visa card' }

console.log(formatCardInfo('4111111111111112'));
// { isValid: false, cardType: 'visa', issues: ['Invalid checksum'], message: 'Invalid card number' }

🛠️ Development

⚙️ Prerequisites

• Node.js (version 14 or higher)
• npm, yarn, or pnpm

🔧 Setup

# Clone the repository
git clone https://github.com/juspay/cards-validator.git
cd cards-validator

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run development mode with watch
npm run dev

📜 Scripts

Script	Description
npm run build	🔨 Compile TypeScript to JavaScript
npm run dev	👀 Watch mode for development
npm test	🧪 Run test suite
npm run clean	🧹 Remove build artifacts
npm run lint	🔍 Run ESLint
npm run format	✨ Format code with Prettier

🧪 Testing

The library includes comprehensive tests covering:

✅ Card type detection for all supported card types
✅ Luhn algorithm validation
✅ Length validation
✅ Edge cases and error handling
✅ Input normalization (spaces, dashes)

Run tests with:

npm test

🤝 Contributing

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📋 Changelog

v0.1.0

• ✨ Initial release
• 💳 Support for 12+ major card types
• ✅ Luhn algorithm validation
• 📏 Length validation
• 📘 TypeScript support
• 🧪 Comprehensive test suite

🙏 Acknowledgments

• 🔐 Luhn Algorithm for card number validation
• 💳 Card type patterns and ranges based on industry standards
• 🌟 Inspired by various open-source card validation libraries

📞 Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.

Made with ❤️ by Juspay Technologies

⭐ Star us on GitHub — it helps us grow!