Credit Card Type

Credit Card Type provides a useful utility method for determining a credit card type from both fully qualified and partial numbers. This is not a validation library but rather a smaller component to help you build your own validation or UI library.

This library is designed for type-as-you-go detection (supports partial numbers) and is written in CommonJS so you can use it in Node, io.js, and the browser.

Download

To install via npm:

npm install credit-card-type

Example

var creditCardType = require("credit-card-type");

// The card number provided should be normalized prior to usage here.
var visaCards = creditCardType("4111");
console.log(visaCards[0].type); // 'visa'

var ambiguousCards = creditCardType("6");
console.log(ambiguousCards.length); // 6
console.log(ambiguousCards[0].niceType); // 'Discover'
console.log(ambiguousCards[1].niceType); // 'UnionPay'
console.log(ambiguousCards[2].niceType); // 'Maestro'

API

creditCardType(number: String)

creditCardType will return an array of objects, each with the following data:

If no card types are found, this returns an empty array.

Note: The card number provided should be normalized ahead of time. The card number string should not contain any non-integer values (e.g. no letters or special characters)

creditCardType.getTypeInfo(type: String)

getTypeInfo will return a singular object (with the same structure as creditCardType) corresponding with the specified type, or undefined if the specified type is invalid/unknown.

Card Type "Constants"

Named variables are provided for each of the supported card types:

• AMERICAN_EXPRESS
• DINERS_CLUB
• DISCOVER
• ELO
• HIPERCARD
• HIPER
• JCB
• MAESTRO
• MASTERCARD
• MIR
• UNIONPAY
• VISA

code

Card brands provide different nomenclature for their security codes as well as varying lengths.

A full response for a Visa card will look like this:

{
  "niceType": "Visa",
  "type": "visa",
  "gaps": [4, 8, 12],
  "lengths": [16],
  "code": { "name": "CVV", "size": 3 }
}

Advanced Usage

CommonJS:

var creditCardType = require("credit-card-type");
var getTypeInfo = require("credit-card-type").getTypeInfo;
var CardType = require("credit-card-type").types;

ES6:

import creditCardType, {
  getTypeInfo,
  types as CardType,
} from "credit-card-type";

Filtering

creditCardType(cardNumber).filter(function (card) {
  return card.type === CardType.MASTERCARD || card.type === CardType.VISA;
});

Pattern Detection

Each card type has a patterns attribute that is an array of numbers and ranges of numbers (represented by an array of 2 values, a min and a max).

If the pattern is a number, the modules compares it against the card number. Partial matches for card numbers that are shorter than the pattern also match. Given the pattern 123, then the card numbers 1, 12, 123, 1234 will all match, but 2, 13, and 124 will not.

If the pattern is an array of numbers, then the card number is checked to be within the range of those numbers. Again, partial matches are accepted. Given the range [100, 123], then the card numbers 1, 10, 100, 12, 120, 123 will all match, but 2, 13, and 124 will not.

For detection, the module loops over each card type's patterns array, and if a match occurs, that card type is added to the array of results.

In the case where multiple matches are made, if the entirety of the pattern is matched, the card type with the stronger pattern is preferred. For instance, Visa cards match anything that starts with a 4, but there are some Elo cards that begin with a 4. One example is 401178. So for the card numbers, 4, 40, 401, 4011, 40117, the module will report that this card is either a Visa or an Elo card. Once the card number becomes 401178, the modules sees that an exact match for the ELO bin has been made, and the module reports that the card can only be an Elo card.

Adding Card Types

You can add additional card brands not supported by the module with addCard. Pass in the configuration object.

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

If you add a card that already exists in the module, it will overwrite it.

creditCardType.addCard({
  niceType: "Visa with Custom Nice Type",
  type: creditCardType.types.VISA,
  patterns: [41111, [44, 47]],
  gaps: [4, 8, 12],
  lengths: [13, 16, 19], // add support for old, deprecated 13 digit visas
  code: {
    name: "CVV",
    size: 3,
  },
});

Adding new cards puts them at the bottom of the priority for testing. Priority is determined by an array. By default, the priority looks like:

[
  creditCardType.types.VISA,
  creditCardType.types.MASTERCARD,
  creditCardType.types.AMERICAN_EXPRESS,
  creditCardType.types.DINERS_CLUB,
  creditCardType.types.DISCOVER,
  creditCardType.types.JCB,
  creditCardType.types.UNIONPAY,
  creditCardType.types.MAESTRO,
  creditCardType.types.ELO,
  creditCardType.types.MIR,
  creditCardType.types.HIPER,
  creditCardType.types.HIPERCARD,
];

You can adjust the order using changeOrder. The number you pass in as the second argument is where the card is inserted into the array. The closer to the beginning of the array, the higher priority it has.

creditCardType.changeOrder("my-new-card", 0); // give custom card type the highest priority
creditCardType.changeOrder("my-new-card", 3); // give it a priority at position 3 in the test order array

You can also remove cards with removeCard.

creditCardType.removeCard(creditCardType.types.VISA);

If you need to reset the modifications you have created, simply call resetModifications:

creditCardType.resetModifications();

Updating Card Types

You can update cards with updateCard. Pass in the card type and the configuration object. Any properties left off will inherit from the original card object.

creditCardType.updateCard(creditCardType.types.VISA, {
  niceType: "Fancy Visa",
  lengths: [11, 16],
});

var visa = creditCardType.getTypeInfo(creditCardType.types.VISA);

// overwritten properties
visa.niceType; // 'Fancy Visa'
visa.length; // [11, 16]

// unchanged properties
visa.gaps; // [4, 8, 12]
visa.code.name; // 'CVV'

If you need to reset the modifications you have created, simply call resetModifications:

creditCardType.resetModifications();

Pretty Card Numbers

function prettyCardNumber(cardNumber, cardType) {
  var card = getTypeInfo(cardType);

  if (card) {
    var offsets = [].concat(0, card.gaps, cardNumber.length);
    var components = [];

    for (var i = 0; offsets[i] < cardNumber.length; i++) {
      var start = offsets[i];
      var end = Math.min(offsets[i + 1], cardNumber.length);
      components.push(cardNumber.substring(start, end));
    }

    return components.join(" ");
  }

  return cardNumber;
}

prettyCardNumber("xxxxxxxxxx343", CardType.AMERICAN_EXPRESS); // 'xxxx xxxxxx 343'

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 and the test suite executed with npm test.

10.0.2

• Update (sub-)dependencies
  • cross-spawn to 7.0.6
  • micromatch to 4.0.8
  • semver to 6.3.1

10.0.1

• Update braces to 3.0.3

10.0.0

• BREAKING CHANGES
  • Update Node to v18 -DevDependencies
  • Update prettier to v3
  • Update eslint-plugin-prettier to v5
  • Typescript to v5

9.1.0

• Add additional Hiper bins (#115 thanks @upigilam)

9.0.1

• Correct issue where ELO cards were misidentified as Maestro cards (thanks @gabrielozaki)

9.0.0

• Add typescript types

Breaking Changes

• Drop Bower Support
• Drop support for card numbers instantiated with new String(number)

8.3.0

• Add support for series 8 UnionPay cards (fixes #95 thanks @leebradley)

8.2.0

• Add 14 and 15 length configuration to UnionPay cards

8.1.0

• Add support for Hiper cards
• Add support for Hipercard cards

8.0.0

• Improve pattern recognition for card types

Breaking Changes

• When adding or updating cards, this module no longer uses an exactPattern and prefixPattern model. Instead, it takes an array of patterns. See https://github.com/braintree/credit-card-type#pattern-detection for details.

7.1.0

• Add support for Elo card type
• Adds updateCard method (#77)

7.0.0

• Updates "master-card" enum to "mastercard"

6.3.0

• Add support for MIR card type (thanks @antongolub)

6.2.0

• Allow custom card brands to be added

6.1.1

• Correct Mastercard bin range for series 2 bins

6.1.0

• Add support for JCB cards of length 17, 18, and 19 (#54, thanks @zeh)

6.0.0

• Update mastercard niceType property to Mastercard to match new brand guidelines

Breaking Changes

• Remove internal properties prefixPattern and exactPattern from returned object

5.0.4

• Correct Discover to respect lengths for international cards
• Make Maestro pattern more exact

5.0.3

• Fix prefix pattern for MasterCard numbers starting with 27

5.0.2

• Fix checking for UnionPay ranges

5.0.1

• Visa cards can now be 16, 18, or 19 digits.

5.0.0

• Card matching has been replaced with a two-tier process. This simplifies the matching process for ambiguous numbers.

• Partial BIN matches (prefixPattern) are accumulated separately from exact BIN matches (exactPattern).

• If there were any exact BIN matches, those matches are returned.
• If there are no exact BIN matches, all partial matches are returned.

4.1.0

• Add getTypeInfo and types exports for getting type information such as number spacing given a type string such as visa.

4.0.3

• Remove behavior where some UnionPay cards displayed Discover and UnionPay as possible card types

4.0.2

• Add support for series 2 MasterCard bins (ranging from 222100 to 272099)
• Removes dependency on Lodash

4.0.1

• Switch to one version of Lodash

4.0.0

• Further resolve ambiguity issues with various cards; return an array of potential card types instead of a single type

3.0.0

• Resolve ambiguity issues with Maestro and Discover cards

2.0.0

• Add support for Maestro and UnionPay
• Change return type of length as a String to lengths as an Array

1.0.0

• Initial Release