Credit Card Utility Methods

Common errors

• TypeError: (0 , creditcards_card__WEBPACK_IMPORTED_MODULE_0__.Card) is not a function

  cause Attempting to import a default export from a sub-module as a named export.
  fix Change `import { Card } from 'creditcards/card';` to `import Card from 'creditcards/card';`.

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... Not supported

  cause Attempting to `require()` an ESM-only module or using CJS `require` in an ESM project for a package that strictly enforces ESM.
  fix Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) and use `import` statements. If sticking to CommonJS, verify the specific `creditcards` version and import path support `require()` for the module you're trying to access.

• card.type is undefined when passing a number like '4242 4242 4242 4242'

  cause `card.type` and `card.isValid` expect a purely numeric string, not one with spaces or other characters.
  fix Always sanitize the card number using `card.parse()` before passing it to `card.type()` or `card.isValid()`: `card.type(card.parse(inputNumber))`.

Warnings

• breaking Version 5.0.0 elevates the minimum Node.js requirement to >= 18. Applications running on older Node.js versions will need to upgrade their environment or stick to an earlier major version of `creditcards`.
  Fix: Upgrade your Node.js runtime to version 18 or newer, or pin `creditcards` to a version less than 5.0.0 (e.g., `creditcards@^4`).
• gotcha When using `card.type()` or `card.isValid()`, ensure the card number is sanitized first using `card.parse()`. These methods expect a purely numeric string without spaces or punctuation.
  Fix: Always pass the output of `card.parse(number)` to `card.type()` or `card.isValid()` to prevent unexpected behavior with non-numeric characters.
• gotcha Individual module imports (e.g., `creditcards/card`) typically export a default function or object, not named exports. Incorrectly using named imports for these paths will lead to `TypeError: (0 , creditcards_card__WEBPACK_IMPORTED_MODULE_0__.Card) is not a function` or similar errors.
  Fix: Use `import Card from 'creditcards/card';` instead of `import { Card } from 'creditcards/card';` for individual module imports. Review the README for correct import patterns for specific sub-modules.
• gotcha The `eager` parameter for `card.type(number, eager)` will match partial card numbers, which can be useful for UI feedback during input but should not be relied upon for final, strict validation of a complete card number.
  Fix: For strict validation of a complete card number, ensure `eager` is `false` or omitted. Use `card.isValid()` for definitive validity checks.

Install

• npm install creditcards npm
• yarn add creditcards yarn
• pnpm add creditcards pnpm

Imports

• card
  wrong:

  const { card } = require('creditcards');

  correct:

  import { card } from 'creditcards';

  Primary entry point for card number utilities (parse, format, type, isValid, luhn). ESM is preferred since v5, though CommonJS `require` still works for the main export.
• cvc
  wrong:

  const { cvc } = require('creditcards');

  correct:

  import { cvc } from 'creditcards';

  Provides CVC validation utilities. Follows the same import pattern as 'card'.
• expiration
  wrong:

  const { expiration } = require('creditcards');

  correct:

  import { expiration } from 'creditcards';

  Offers utilities for parsing and validating expiration months and years. Follows the same import pattern as 'card'.
• Card
  wrong:

  import { Card } from 'creditcards/card';

  correct:

  import Card from 'creditcards/card';

  When importing individual modules like 'creditcards/card', they typically expose a default function. This pattern is useful for injecting custom card types.

Quickstart

This quickstart demonstrates common usage patterns for credit card validation and formatting, including parsing, formatting, type detection, Luhn algorithm check, CVC validation, and expiration date checks. It also shows how to customize card types using `withTypes`.

import { card, cvc, expiration, withTypes } from 'creditcards';
import { visa, mastercard } from 'creditcards-types';

// --- Card Utilities ---
const rawCardNumber = '  4242-4242-4242-4242  ';
const parsedCardNumber = card.parse(rawCardNumber); // '4242424242424242'
const formattedVisa = card.format(parsedCardNumber); // '4242 4242 4242 4242'
const cardType = card.type(parsedCardNumber); // 'visa'
const isValidLuhn = card.luhn(parsedCardNumber); // true
const isValidCard = card.isValid(parsedCardNumber); // true
const isValidVisa = card.isValid(parsedCardNumber, 'visa'); // true

console.log(`Parsed Card: ${parsedCardNumber}`);
console.log(`Formatted Card: ${formattedVisa}`);
console.log(`Card Type: ${cardType}`);
console.log(`Luhn Valid: ${isValidLuhn}`);

// --- CVC Utilities ---
const cvcValue = '123';
const isValidCVC = cvc.isValid(cvcValue, 'visa'); // true
console.log(`CVC Valid for Visa: ${isValidCVC}`);

// --- Expiration Utilities ---
const currentMonth = new Date().getMonth() + 1;
const currentYear = new Date().getFullYear();
const futureYear = currentYear + 5;

const isMonthValid = expiration.month.isValid(currentMonth); // true
const isYearValid = expiration.year.isValid(futureYear); // true
const isPast = expiration.isPast(currentMonth - 1, currentYear); // true (assuming currentMonth > 1)

console.log(`Expiration Month Valid: ${isMonthValid}`);
console.log(`Expiration Year Valid: ${isYearValid}`);
console.log(`Is past (last month): ${isPast}`);

// --- Using custom types (requires 'creditcards-types') ---
const customCardModule = withTypes([visa, mastercard]);
const isAmexWithCustomTypes = customCardModule.card.isValid('378282246310005', 'american-express'); // false if only visa/mastercard are included
console.log(`Is Amex valid with custom types (only Visa/MC): ${isAmexWithCustomTypes}`);