/card-validator

Validate credit cards as users type.

Primary LanguageJavaScriptMIT LicenseMIT

Credit Card Validator Build Status npm version

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): 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
}

If a valid card type cannot be determined, number() will return 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.expirationDate(value: string|object, maxElapsedYear: integer): object

The maxElapsedYear has a default value of 19. 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'}
{month: '01', year: '19'}
{month: '1', year: '19'}
{month: 1, year: 19}		 {month: '01', year: '19'}
{month: '10', year: '2019'}
{month: '1', year: '2019'}
{month: 1, year: 19}		 {month: '10', 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 has a default value of 19. 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 tests for a valid string greater than 3 characters in length.

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

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',
  prefixPattern: /^(2|23|234)$/,
  exactPattern: /^(2345)\d*$/,
  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.