creditcards

library5.0.0jsnpmunverified

The `creditcards` package provides a suite of utility methods for parsing, formatting, and validating credit card numbers, CVCs, and expiration dates. Currently at version 5.0.0, it offers a robust solution for handling common payment-related data operations in applications. While no explicit release cadence is stated, the package is actively maintained and ships with TypeScript types, promoting type safety and improved developer experience. A key differentiator is its modular design, allowing developers to import specific functionalities like `card` or `expiration` individually, and the ability to inject custom card types via the `withTypes` function or by importing individual modules from `creditcards-types` to extend supported card schemas beyond the defaults. It targets modern Node.js environments (>= 18).

payments serialization type-stubs

npm install creditcards

github ↗package ↗

INSTALL

IMPORT

SIG · CREDITCARDS

creditcards

paymentsjavascriptv5.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

card

✓ import { card } from 'creditcards';

✗ const { card } = require('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

✓ import { cvc } from 'creditcards';

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

Provides CVC validation utilities. Follows the same import pattern as 'card'.

expiration

✓ import { expiration } from 'creditcards';

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

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

Card

✓ import Card from 'creditcards/card';

✗ 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.

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}`);

Debug

Known issues

breakingVersion 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`).

affects: >=5.0.0

gotchaWhen 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.

affects: >=1.0.0

gotchaIndividual 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.

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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

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'

`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))`.

Upgrade

Version history

5.0.0latest on npm

Audit

Dependencies

creditcards-typesoptionalProvides default and custom card type definitions for advanced usage or extending support for specific card schemes.

Agent activity

37 hits · last 30 days

node

Resources

githubhttps://github.com/bendrucker/creditcards ↗

packagehttps://www.npmjs.com/package/creditcards ↗