braintree/card-validator

Validate credit cards as users type.

Credit Card Validator

Credit Card Validator provides validation utilities for credit card data inputs. It is designed as a CommonJS module for use in Node.js, io.js, or the browser. It includes first class support for 'potential' validity so you can use it to present appropriate UI to your user as they type.

A typical use case in a credit card form is to notify the user if the data they are entering is invalid. In a credit card field, entering “411” is not necessarily valid for submission, but it is still potentially valid. Conversely, if a user enters “41x” that value can no longer pass strict validation and you can provide a response immediately.

Credit Card Validator will also provide a determined card type (using credit-card-type). This is useful for scenarios in which you wish to render an accompanying payment method icon (Visa, MasterCard, etc.). Additionally, by having access to the current card type, you can better manage the state of your credit card form as a whole. For example, if you detect a user is entering (or has entered) an American Express card number, you can update the maxlength attribute of your CVV input element from 3 to 4 and even update the corresponding label from 'CVV' to 'CID'.

Download

You can install card-validator through npm.

npm install card-validator

Example

Using a CommonJS build tool (browserify, webpack, etc)

var valid = require("card-validator");

var numberValidation = valid.number("4111");

if (!numberValidation.isPotentiallyValid) {
  renderInvalidCardNumber();
}

if (numberValidation.card) {
  console.log(numberValidation.card.type); // 'visa'
}

API

var valid = require('card-validator');

---

valid.number(value: string, [options: object]): object

{
  card: {
    niceType: 'American Express',
    type: 'american-express',
    gaps: [4, 10],
    lengths: [15],
    code: {name: 'CID', size: 4}
  },
  isPotentiallyValid: true, // if false, indicates there is no way the card could be valid
  isValid: true // if true, number is valid for submission
}

You can optionally pass luhnValidateUnionPay as a property of an object as a second argument. This will override the default behavior to ignore luhn validity of UnionPay cards.

valid.number(<Luhn Invalid UnionPay Card Number>, {luhnValidateUnionPay: true});

{
  card: {
    niceType: 'UnionPay',
    type: 'unionpay',
    gaps: [4, 8, 12],
    lengths: [16, 17, 18, 19],
    code: {name: 'CVN', size: 3}
  },
  isPotentiallyValid: true,
  isValid: false // Would be true if no options were included
}

You can optionally pass maxLength as a property of an object as a second argument. This will override the default behavior to use the card type's max length property and mark any cards that exceed the max length as invalid.

If a card brand has a normal max length that is shorter than the passed in max length, the validator will use the shorter one. For instance, if a maxLength of 16 is provided, the validator will still use 15 as the max length for American Express cards.

You can optionally pass skipLuhnValidation: true as a property of an object as a second argument. This will override the default behaviour and will skip the validation of the check digit of the card number using Luhn Algorithm. The skipLuhnValidation should not be set to true in production environment.

valid.number(<Maestro Card with 19 Digits>, {maxLength: 16});

{
  card: {
    // Maestro card data
  },
  isPotentiallyValid: false,
  isValid: false
}

If a valid card type cannot be determined, the card field in the response will be null.

A fake session where a user is entering a card number may look like:

Input	Output			Suggested Handling
Value	card.type	isPotentiallyValid	isValid	Render Invalid UI	Allow Submit
''	null	true	false	no	no
'6'	null	true	false	no	no
'60'	'discover'	true	false	no	no
'601'	'discover'	true	false	no	no
'6011'	'discover'	true	false	no	no
'601'	'discover'	true	false	no	no
'60'	'discover'	true	false	no	no
'6'	null	true	false	no	no
''	null	true	false	no	no
'x'	null	false	false	yes	no
''	null	true	false	no	no
'4'	'visa'	true	false	no	no
'41'	'visa'	true	false	no	no
'411'	'visa'	true	false	no	no
'4111111111111111'	'visa'	true	true	no	yes
'411x'	null	false	false	yes	no

---

valid.cardholderName(value: string): object

The cardholderName validation essentially tests for a valid string greater than 0 characters in length that does not look like a card number.

{
  isPotentiallyValid: true,
  isValid: true
}

If a cardholder name is comprised of only numbers, hyphens and spaces, the validator considers it to be too card-like to be valid, but may still be potentially valid if a non-numeric character is added. This is to prevent card number values from being sent along as the cardholder name but not make too many assumptions about a person's cardholder name.

{
  isPotentiallyValid: true,
  isValid: false
}

If a cardholder name is longer than 255 characters, it is assumed to be invalid.

{
  isPotentiallyValid: false,
  isValid: false
}

valid.expirationDate(value: string|object, maxElapsedYear: integer): object

The maxElapsedYear parameter determines how many years in the future a card's expiration date should be considered valid. It has a default value of 19, so cards with an expiration date 20 or more years in the future would not be considered valid. It can be overridden by passing in an integer as a second argument.

{
  isPotentiallyValid: true, // if false, indicates there is no way this could be valid in the future
  isValid: true,
  month: '10', // a string with the parsed month if valid, null if either month or year are invalid
  year: '2016' // a string with the parsed year if valid, null if either month or year are invalid
}

expirationDate will parse strings in a variety of formats:

Input	Output
'10/19' '10 / 19' '1019' '10 19'	{month: '10', year: '19'}
'10/2019' '10 / 2019' '102019' '10 2019' '10 19'	{month: '10', year: '2019'}
'2019-10'	{month: '10', year: '2019'}
{month: '01', year: '19'} {month: '1', year: '19'} {month: 1, year: 19}	{month: '01', year: '19'}
{month: '01', year: '2019'} {month: '1', year: '2019'} {month: 1, year: 2019}	{month: '01', year: '2019'}

---

valid.expirationMonth(value: string): object

expirationMonth accepts 1 or 2 digit months. 1, 01, 10 are all valid entries.

{
  isValidForThisYear: false,
  isPotentiallyValid: true,
  isValid: true
}

---

valid.expirationYear(value: string, maxElapsedYear: integer): object

expirationYear accepts 2 or 4 digit years. 16 and 2016 are both valid entries.

The maxElapsedYear parameter determines how many years in the future a card's expiration date should be considered valid. It has a default value of 19, so cards with an expiration date 20 or more years in the future would not be considered valid. It can be overridden by passing in an integer as a second argument.

{
  isCurrentYear: false,
  isPotentiallyValid: true,
  isValid: true
}

---

valid.cvv(value: string, maxLength: integer): object

The cvv validation by default tests for a numeric string of 3 characters in length. The maxLength can be overridden by passing in an integer as a second argument. You would typically switch this length from 3 to 4 in the case of an American Express card which expects a 4 digit CID.

{
  isPotentiallyValid: true,
  isValid: true
}

---

valid.postalCode(value: string, [options: object]): object

The postalCode validation essentially ignores leading/trailing whitespace and tests for a valid string greater than 3 characters in length. It also verifies that the first 3 letters are alphanumeric.

{
  isPotentiallyValid: true,
  isValid: true
}

You can optionally pass minLength as a property of an object as a second argument. This will override the default min length of 3 and verify that the characters for the specified length are all alphanumeric.

valid.postalCode('123', {minLength: 5});

{
  isPotentiallyValid: true,
  isValid: false
}

Custom Card Brands

Card Validator exposes the credit-card-type module as creditCardType. You can add custom card brands by utilizing the addCard method.

valid.creditCardType.addCard({
  niceType: "NewCard",
  type: "new-card",
  patterns: [1234],
  gaps: [4, 8, 12],
  lengths: [16],
  code: {
    name: "CVV",
    size: 3,
  },
});

Design decisions

• The default maximum expiration year is 19 years from now.
• valid.expirationDate will only return month: and year: as strings if the two are valid, otherwise they will be null.
• Since non-US postal codes are alpha-numeric, the postalCode will allow non-number characters to be used in validation.

Development

We use nvm for managing our node versions, but you do not have to. Replace any nvm references with the tool of your choice below.

nvm install
npm install

All testing dependencies will be installed upon npm install. Run the test suite with npm test.

card-validator's Issues

Debit card support

Hello folks!, Is there any plan to add support for debit card validation such as SEPA direct debit or ELV?

Feature request: Add custom card type

General information

We want to this cool library in our repository. But we need to be able to specify other card types, such as MIR for instance.

Issue description

I can see PR in credit-card-type repository with described functionality. braintree/credit-card-type#67

Is it possible to add this functionality even to this library? 🙏

How to use this without building?

I'm trying to use this directly in the client browser to validate card information before they hit submit.

I don't want to use bower/npm or any build environment.

I saw another issue that said it would be in the dist folder but I don't see that anymore. I've also tried building it myself locally with a number of different commands and that doesn't seem to work either.

Thanks!

PS... its really absolutely crazy to me this is the ONLY credit card validation library I can find online............. all the others are 5+ years old. How is that even possible, it is mind blowing. The only other ones are by Stripe but it only works with stripe api keys etc.

Add general check to make sure that postal codes are alphanumeric codes only

Title explains it all. Happy to send in a PR when I get the chance.

Visa Card Length 13 is not Valid

General information

• Library version: @latest

Issue description

Visa card lengths is always [16, 18, 19], so it doesn't allow other lengths like 13 or 14. Can you please tell me how to fix this?
Thanks!

Using the library without building with npm

Would love to use this library as is without using npm or any other build tool. How do i use it?

Am still an old school developer that include js library in webpage header and stuff.

Dates that are input as MM/YY that are invalid, but could be valid once the full MM/YYYY date is input should be marked as potentially valid

For instance, currently the date 02/20 is marked as:

isValid: false,
isPotentiallyValid: false

But if the customer continues typing to make the date 02/2023, then the date becomes valid, so 02/20 should be marked as potentiallyValid: true

We basically need to grab the YY value from MM/YY and detect if any combination of the final 2 values would be valid. If so, then it is potentially valid.

Cant ID JCB and Enroute cards

General information

• Library version: 4.1.0

Issue description

Can't identify these cards:

214930167048081 - enroute
3112904154980561 - JCB
180088790420118 - JCB

Using these online tool to verify validity of the above cards:
https://names.igopaygo.com/credit-card/validate
https://www.tools4noobs.com/online_tools/credit_card_validate/

Won't compile when targeting ECMAScript modules

General information

• Library version: 8.1.0
• Browser and OS N/A

Issue description

Imported to an Angular 11 / TypeScript project as:
import * as cardValidator from 'card-validator';
import { CardNumberVerification } from 'card-validator/src/card-number';

Usage:
const result: CardNumberVerification = cardValidator.number(value);

Errors on project compilation:
Error: node_modules/card-validator/src/card-number.ts:1:1 - error TS1202: Import assignment cannot be used when targeting ECMAScript modules. Consider using 'import * as ns from "mod"', 'import {a} from "mod"', 'import d from "mod"', or another module format instead.

1 import luhn10 = require("./luhn-10");

Error: node_modules/card-validator/src/card-number.ts:1:25 - error TS7016: Could not find a declaration file for module './luhn-10'. '/Users/russcarver/Code/patientpay/node_modules/card-validator/src/luhn-10.js' implicitly has an 'any' type.

1 import luhn10 = require("./luhn-10");
                        ~~~~~~~~~~~


Error: node_modules/card-validator/src/card-number.ts:2:1 - error TS1202: Import assignment cannot be used when targeting ECMAScript modules. Consider using 'import * as ns from "mod"', 'import {a} from "mod"', 'import d from "mod"', or another module format instead.

2 import getCardTypes = require("credit-card-type");

Strange bug with valid.expirationDate returning incorrect result in 2020

General information

• Library version: 10.0.0
• Browser and OS: Chrome 127.0.6533.119 (64-bit) on MacOS 14.5

Issue description

Our test suites set the test suite time 2020-01-01 (using mockdate), and we have a test to check that valid.expirationDate will return isValid: true for "07/20". This works on versions 7 and below, but on version 8 up, it returns isValid: false.

Changing the tests to any year other than 2020 seems to work fine, but I can't work out why it doesn't work on that particular year.

To replicate it, install jest and mockdate, and then run the following test suite:

const valid = require('card-validator')
const MockDate = require('mockdate')

beforeAll(() => {
  MockDate.set('2020-01-01')
})

it('is valid', () => {
  const result = valid.expirationDate('07/20').isValid

  expect(result).toBe(true)
})

On versions 7 and below, this will pass as expected. But on versions 8 and above it fails.

Alternatively you can replicate it by simply setting your own system date to 2020-01-01, and then run console.log(valid.expirationDate('07/20')), which will incorrectly return isValid: false on versions 8 and above.

Use lodash base package instead of function modules

This might be a controversial request, but I was wondering if you were inclined to change the dependencies on lodash.assign lodash.isnumber and lodash.isstring just to lodash and then require just the sub-modules, as in var assign = require('lodash/object/assign') etc.

The reasoning behind this is that projects which already use lodash as dependency will have to carry an additional weight in their payload file due to those custom lodash builds, instead of being able to utilize the same assign, isNumber and isString functions, which they might already be depending on anyway.

Potentially valid expiry date being marked as invalid

The entry '123' is being marked as

{ isValid: false, isPotentiallyValid: false, month: '1', year: '23' }

However, 12/30 is valid, and I believe this should return true for isPotentiallyValid

Problem with validating cvv

I'm trying to validate a cvv for an American Express card, which expects a length of 4. I have a scenario where value=123 and maxLength=4 and I expect the cvv to not be valid, but it always says it is valid.

Does cvv validation just check for maxLength, and if it's less than that then it's valid? That doesn't make sense to me.. The problem is occurring in the min function, where it will always return the minimum DEFAULT_LENGTH if the maxLength I pass in is greater than it.

Add Browserify standalone option

As suggested by @muffinresearch in #2 (comment), to better support AMD and global export for browser builds, we can add a standalone namespace to our browserify config. For example:

return browserify({
  standalone: 'card-validator',
  entries: config.src.js.main
})

Stripe

{
"object": {
"object": "balance",
"available": [
{
"amount": 0,
"currency": "usd",
"source_types": {
"card": 0
}
}
],
"connect_reserved": [
{
"amount": 0,
"currency": "usd"
}
],
"issuing": {
"available": [
{
"amount": 2088,
"currency": "usd"
}
]
},
"livemode": true,
"pending": [
{
"amount": 0,
"currency": "usd",
"source_types": {
"card": 0
}
}
]
}
}

Card number validation fails if there are multiple potencial card types

General information

• Library version: 5.1.0
• Browser and OS: Server (NodeJS v10.10.0)

Issue description

Currently, the card number validation logic does not allow multiple potencial card types.

card-validator/src/card-number.js

Lines 29 to 31 in 2f14aed

	} else if (potentialTypes.length !== 1) {
	return verification(null, true, false);
	}

It means that even if the card number is completely valid based on luhn algorithm, the validation result will always return isValid as false.

Here is a example of a valid card number, which can be Elo or Maestro:

const cardValidator = require('card-validator');
const cardValidationResult = cardValidator.number('5067278453558075'); // This is a Elo card number that was generated in https://developer.paypal.com/developer/creditCardGenerator/

console.log(cardValidationResult);

// The validation above returns:
// {
//   card: null,
//   isPotentiallyValid: true,
//   isValid: false
// }

I believe this behavior was created to avoid the card type to be specified very early, when the user is typing the first numbers still. Ex: only typing 5 could trigger the card type to be Visa, but it can be Visa, Maestro or Elo.

Possible solutions

1. Since most patterns are based on the first 4-6 digits, we can add a logic that only triggers this behavior if the user didn't type more than 5 digits. The first potencial card type is returned, since we can control the order of the card types.
2. We can update the Elo card patterns, but it's hard to maintain and it can lead to similar problems in the future, since new card bins can be added.

feat: Validate if the card has expired.

Feature Request

Validate if the card expiration month and year are in the past.

Currently, we can check that the month and year separately are valid, and that the expire date is within the next 19 years, but we cant check if they are in the past.

If the current date is December 2020, entering "07 2020" is still a valid expiration date according to the methods on this library.

Broken module imports

General information

• Library version: React Native
• Browser and OS : Android

Issue description

Looks like the default export of the module is broken , so imports like import valid from 'card-validator' dont work any more , one has to use the named Exports ie this works , import {number, expirationDate, cvv} from 'card-validator'.

Bower integration

Can you put this repo also on bower? I think it will be useful for all those users who are not using npm, but only bower as package manager.

Question about brands

Hello!

I'm trying to find what brands are supported by the lib,
but i cant find in anywhere, can you help me?
To be more specific, i'm trying to find about PRESTO and MAGNA

isPotentiallyValid not working correctly with MC bins 222100–272099

General information

• Library version: 4.1.0
• Browser and OS: N/A but Chrome 58.0.3029.110 (64 bit) on MacOS 10.12.4 -->

Issue description

It looks like there is an issue with isPotentiallyValid returning false when there could still be a match for MasterCard. In my scenario I was entering in a MC in the bin range 222100–272099 and once I entered in 27, isPotentiallyValid returns false. If I continue to type in 7 it is still false but once I type 0 is is now potentially valid again.

It seems like this shouldn't be returning false so quickly considering there are patterns that it could match.

so again steps to reproduce ->

var valid = require('card-validator');

var numberValidation = valid.number('27');
console.log(numberValidation.isPotentiallyValid); // false

numberValidation = valid.number('272');
console.log(numberValidation.isPotentiallyValid); // false

numberValidation = valid.number('2720');
console.log(numberValidation.isPotentiallyValid); // true

Request: Document the `maxElapsedYear` option

Request: Add some documentation in the readme for the maxElapsedYear option. I had to look at the code to figure out what maxElapsedYear actually does. Thanks for building/maintaining this library. It looks great!

American Express Credit Cards always return invalid

General information

Not sure if this is an issue or not but I do not even remotely comprehend how this keeps returning as a failure on amex.

cardValidator.number(number, { maxLength: 15}).isPotentiallyValid

This returns failed repeatedly with 5 different amex cards. Is there something special for amex that isnt listed in the documentation?

Issue description

Valid Card Holder Name?

Add Card Holder Name validation.

Example

• Block non ascii characters é, á, ú, ç
• Enforce Card Holder max length
• All UPPERCASE

Visa especial credit card number marked as invalid

General information

• Library version: 4.1.0
• Browser and OS: Node.js in Windows

Issue description

Using paypal suggested valid credit cards: https://www.paypalobjects.com/en_AU/vhelp/paypalmanager_help/credit_card_numbers.htm we receive this credit card 4222222222222 as invalid, but they said that this is a valid credit card number.

4222222222222
Note : Even though this number has a different character count than the other test numbers, it is the ?
correct and functional number.

Doing research in internet, it says that visa has a lenght of 13 or 16, but right now the package is only validating 16.

Maybe we need to add a validation for this credit card number length for visa credit cards?

number() is returning incorrect values for a single char

If you enter '3' into card-validator.number() isPotentiallyValid is false. This doesn't make sense as adding a '7' and it's detected as amex. See below a screenshot showing the issue.

STR

npm install card-validator
node

cv = require('card-validator');
// Compare the output of the following:
cv.number('4');
cv.number('3');
cv.number('37');

Bower support

Is it possible to have bower support?

Card validation

Typescript declaration files breaks the code

General information

• Library version: 8.0.0
• Browser and OS: Chrome: 84.0.4147.125 (Official Build) (64-bit) on MacOS 10.13.6

Issue description

I installed the package via yarn for my React project written in TS. When I import the module like so,

import valid from "card-validator";

everything breaks with many type errors in the console:

I thought I was on an outdated TS version, 3.5.3, so I tried bumping it to the newest, 3.7.2, but I got the same errors.

I also tried installing it on one of my JS projects and it worked fine.

Typescript compile error in index.d.ts "uses 'export =' and cannot be used with 'export *'"

General information

• Library version: 9.0.0
• Typescript version: 3.9.6
• Browser: Windows 10

Issue description

Getting compile error

ERROR in node_modules/card-validator/dist/index.d.ts:7:33 - error TS2498: Module '"C:/_work/websites/..../node_modules/credit-card-type/dist/index"' uses 'export =' and cannot be used with 'export *'.
export * as creditCardType from "credit-card-type";

Here is a picture of the file node_modules/card-validator/dist/index.d.ts

Cc validate

update for mastercard 2 series?

Will there be an update that will incorporate master card series 2 BINs?

https://www.mastercard.us/en-us/issuers/get-support/2-series-bin-expansion.html

UMD bundle missing from npm module

The readme says:

You can install card-validator through npm. The npm module also includes the built, UMD bundle and its minified variant under dist/.

The dist folder is in .npmignore and not included in the npm module.

Why is luhnValidateUnionPay an option?

Why are they not checked by default?

[Question]: how to add custom card brands right way?

General information

• Library version: ^8.1.0

Issue description

I'm using card-validator inside react and added custom card brand always return invalid, in addition, it has a conflict with another card types. so I need to override or add the custom brand the right way, here is an example.

const valid = require('card-validator');

valid.creditCardType.addCard({
  niceType: 'MyCard',
  type: 'mycard',
  patterns: [XXXX],
  gaps: [4, 8, 12],
  lengths: [16],
  code: {
    name: 'CVC',
    size: 3,
  },
});


valid.creditCardType.changeOrder('meezacard', 0);
valid.creditCardType.removeCard(valid.creditCardType.types.CONFLICT);

function CardNumberField() {
  const onChange(ev) {
    const validator = valid.number(ev);
    console.log(validator);
    // Result
   { "card":{
      "niceType":"MyCard",
      "type":"mycard",
      "patterns":[XXXX],
       gaps: [4, 8, 12],
      lengths: [16],
      "code":{ "name":"CVC", "size":3},
      "matchStrength":4
    },
   "isPotentiallyValid":false,
   "isValid":false
   }}
  }

Rub

Why is the "Latest" tag release listed as six years ago?

There's a regular stream of great checkins to the master repo but I was confused by the date on the most recent release (being six years ago). Why is this?
Thanks!

Maestro validation

Hi,

Thanks for this great lib!

There seems to be a problem with the Maestro pattern :

var valid = require('card-validator');
valid.number('500000000000').isPotentiallyValid // false
valid.number('5000000000000611').isPotentiallyValid // true
valid.number('5000000000000611').isValid // true

Many thanks

iOS/MacOS 12.1 Safari Autocomplete issues

General information

• Library version: 6.1.0
• Browser and OS MacOS/iOS + Safari 12.1

Issue description

It seems that Safari auto-completes a cc-expiry field using an extremely bad YYYY-MM format instead of the standard MM / YY format. Since we can't change how Safari decides to autocomplete expiry fields, it might be a good idea for this library to support this format.

For now I've hacked the input to be reformatted for this library using this snippet:

    // This detects Safari auto-fill of expiry date which comes in the format of YYYY-MM
    if (value.match(/^\d{4}-\d{2}$/)) {
      // Split the Year and Month back apart, put it into a correct value
      const appleSplit = value.split('-')
      const rawValue = appleSplit[1] + appleSplit[0]
    }

Postal Code is reporting valid if entire postal code is Empty String

General information

• Library version: 9.1.0

Issue description

Originally raised here -> braintree/braintree-web#714

When a user submits a string with three spaces, the module reports the postal code as valid. While some postal codes do have whitespace in them (UK postal codes, for example), we should look into adding a check to see if the string contains some alpha-numeric values in them or else should be reported as invalid if the entire string is whitespace.

Type missing [@types - dt]

Hi all,
Would be great if we could have a typed version of this module.

Accessing the built source

Consumers of this package probably only want the built source. Would it be possible to make available the built source in npm and bower?