CreditCardValidator.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.validator.routines;

  19. import java.io.Serializable;
  20. import java.util.ArrayList;
  21. import java.util.Collections;
  22. import java.util.List;

  24. import org.apache.commons.validator.GenericValidator;
  25. import org.apache.commons.validator.routines.checkdigit.CheckDigit;
  26. import org.apache.commons.validator.routines.checkdigit.LuhnCheckDigit;

  28. /**
  29.  * Perform credit card validations.
  30.  *
  31.  * <p>
  32.  * By default, AMEX + VISA + MASTERCARD + DISCOVER card types are allowed.  You can specify which
  33.  * cards should pass validation by configuring the validation options. For
  34.  * example,
  35.  * </p>
  36.  *
  37.  * <pre>
  38.  * <code>CreditCardValidator ccv = new CreditCardValidator(CreditCardValidator.AMEX + CreditCardValidator.VISA);</code>
  39.  * </pre>
  40.  *
  41.  * <p>
  42.  * configures the validator to only pass American Express and Visa cards.
  43.  * If a card type is not directly supported by this class, you can create an
  44.  * instance of the {@link CodeValidator} class and pass it to a {@link CreditCardValidator}
  45.  * constructor along with any existing validators. For example:
  46.  * </p>
  47.  *
  48.  * <pre>
  49.  * <code>CreditCardValidator ccv = new CreditCardValidator(
  50.  *     new CodeValidator[] {
  51.  *         CreditCardValidator.AMEX_VALIDATOR,
  52.  *         CreditCardValidator.VISA_VALIDATOR,
  53.  *         new CodeValidator("^(4)(\\d{12,18})$", LUHN_VALIDATOR) // add VPAY
  54.  * };</code>
  55.  * </pre>
  56.  *
  57.  * <p>
  58.  * Alternatively you can define a validator using the {@link CreditCardRange} class.
  59.  * For example:
  60.  * </p>
  61.  *
  62.  * <pre>
  63.  * <code>CreditCardValidator ccv = new CreditCardValidator(
  64.  *    new CreditCardRange[]{
  65.  *        new CreditCardRange("300", "305", 14, 14), // Diners
  66.  *        new CreditCardRange("3095", null, 14, 14), // Diners
  67.  *        new CreditCardRange("36",   null, 14, 14), // Diners
  68.  *        new CreditCardRange("38",   "39", 14, 14), // Diners
  69.  *        new CreditCardRange("4",    null, new int[] {13, 16}), // VISA
  70.  *    }
  71.  * );
  72.  * </code>
  73.  * </pre>
  74.  * <p>
  75.  * This can be combined with a list of {@code CodeValidator}s
  76.  * </p>
  77.  * <p>
  78.  * More information can be found in Michael Gilleland's essay
  79.  * <a href="http://web.archive.org/web/20120614072656/http://www.merriampark.com/anatomycc.htm">Anatomy of Credit Card Numbers</a>.
  80.  * </p>
  81.  *
  82.  * @since 1.4
  83.  */
  84. public class CreditCardValidator implements Serializable {

  86.     /**
  87.      * Class that represents a credit card range.
  88.      * @since 1.6
  89.      */
  90.     public static class CreditCardRange {
  91.         final String low; // e.g. 34 or 644
  92.         final String high; // e.g. 34 or 65
  93.         final int minLen; // e.g. 16 or -1
  94.         final int maxLen; // e.g. 19 or -1
  95.         final int lengths[]; // e.g. 16,18,19

  97.         /**
  98.          * Create a credit card range specifier for use in validation
  99.          * of the number syntax including the IIN range.
  100.          * <p>
  101.          * The low and high parameters may be shorter than the length
  102.          * of an IIN (currently 6 digits) in which case subsequent digits
  103.          * are ignored and may range from 0-9.
  104.          * </p>
  105.          * <p>
  106.          * The low and high parameters may be different lengths.
  107.          * e.g. Discover "644" and "65".
  108.          * </p>
  109.          * @param low the low digits of the IIN range
  110.          * @param high the high digits of the IIN range
  111.          * @param minLen the minimum length of the entire number
  112.          * @param maxLen the maximum length of the entire number
  113.          */
  114.         public CreditCardRange(final String low, final String high, final int minLen, final int maxLen) {
  115.             this.low = low;
  116.             this.high = high;
  117.             this.minLen = minLen;
  118.             this.maxLen = maxLen;
  119.             this.lengths = null;
  120.         }

  122.         /**
  123.          * Create a credit card range specifier for use in validation
  124.          * of the number syntax including the IIN range.
  125.          * <p>
  126.          * The low and high parameters may be shorter than the length
  127.          * of an IIN (currently 6 digits) in which case subsequent digits
  128.          * are ignored and may range from 0-9.
  129.          * </p>
  130.          * <p>
  131.          * The low and high parameters may be different lengths.
  132.          * e.g. Discover "644" and "65".
  133.          * </p>
  134.          * @param low the low digits of the IIN range
  135.          * @param high the high digits of the IIN range
  136.          * @param lengths array of valid lengths
  137.          */
  138.         public CreditCardRange(final String low, final String high, final int [] lengths) {
  139.             this.low = low;
  140.             this.high = high;
  141.             this.minLen = -1;
  142.             this.maxLen = -1;
  143.             this.lengths = lengths.clone();
  144.         }
  145.     }

  147.     private static final long serialVersionUID = 5955978921148959496L;

  149.     private static final int MIN_CC_LENGTH = 12; // minimum allowed length

  151.     private static final int MAX_CC_LENGTH = 19; // maximum allowed length

  153.     /**
  154.      * Option specifying that no cards are allowed.  This is useful if
  155.      * you want only custom card types to validate so you turn off the
  156.      * default cards with this option.
  157.      *
  158.      * <pre>
  159.      * <code>
  160.      * CreditCardValidator v = new CreditCardValidator(CreditCardValidator.NONE);
  161.      * v.addAllowedCardType(customType);
  162.      * v.isValid(aCardNumber);
  163.      * </code>
  164.      * </pre>
  165.      */
  166.     public static final long NONE = 0;

  168.     /**
  169.      * Option specifying that American Express cards are allowed.
  170.      */
  171.     public static final long AMEX = 1 << 0;

  173.     /**
  174.      * Option specifying that Visa cards are allowed.
  175.      */
  176.     public static final long VISA = 1 << 1;

  178.     /**
  179.      * Option specifying that Mastercard cards are allowed.
  180.      */
  181.     public static final long MASTERCARD = 1 << 2;

  183.     /**
  184.      * Option specifying that Discover cards are allowed.
  185.      */
  186.     public static final long DISCOVER = 1 << 3; // CHECKSTYLE IGNORE MagicNumber

  188.     /**
  189.      * Option specifying that Diners cards are allowed.
  190.      */
  191.     public static final long DINERS = 1 << 4; // CHECKSTYLE IGNORE MagicNumber

  193.     /**
  194.      * Option specifying that VPay (Visa) cards are allowed.
  195.      * @since 1.5.0
  196.      */
  197.     public static final long VPAY = 1 << 5; // CHECKSTYLE IGNORE MagicNumber

  199.     /**
  200.      * Option specifying that Mastercard cards (pre Oct 2016 only) are allowed.
  201.      * @deprecated for use until Oct 2016 only
  202.      */
  203.     @Deprecated
  204.     public static final long MASTERCARD_PRE_OCT2016 = 1 << 6; // CHECKSTYLE IGNORE MagicNumber

  206.     /**
  207.      * Luhn checkdigit validator for the card numbers.
  208.      */
  209.     private static final CheckDigit LUHN_VALIDATOR = LuhnCheckDigit.LUHN_CHECK_DIGIT;

  211.     /**
  212.      * American Express (Amex) Card Validator
  213.      * <ul>
  214.      * <li>34xxxx (15)</li>
  215.      * <li>37xxxx (15)</li>
  216.      * </ul>
  217.      */
  218.     public static final CodeValidator AMEX_VALIDATOR = new CodeValidator("^(3[47]\\d{13})$", LUHN_VALIDATOR);

  220.     /**
  221.      * Diners Card Validator
  222.      * <ul>
  223.      * <li>300xxx - 305xxx (14)</li>
  224.      * <li>3095xx (14)</li>
  225.      * <li>36xxxx (14)</li>
  226.      * <li>38xxxx (14)</li>
  227.      * <li>39xxxx (14)</li>
  228.      * </ul>
  229.      */
  230.     public static final CodeValidator DINERS_VALIDATOR = new CodeValidator("^(30[0-5]\\d{11}|3095\\d{10}|36\\d{12}|3[8-9]\\d{12})$", LUHN_VALIDATOR);

  232.     /**
  233.      * Discover Card regular expressions
  234.      * <ul>
  235.      * <li>6011xx (16)</li>
  236.      * <li>644xxx - 65xxxx (16)</li>
  237.      * </ul>
  238.      */
  239.     private static final RegexValidator DISCOVER_REGEX = new RegexValidator("^(6011\\d{12,13})$", "^(64[4-9]\\d{13})$", "^(65\\d{14})$", "^(62[2-8]\\d{13})$");

  241.     /** Discover Card Validator */
  242.     public static final CodeValidator DISCOVER_VALIDATOR = new CodeValidator(DISCOVER_REGEX, LUHN_VALIDATOR);

  244.     /**
  245.      * Mastercard regular expressions
  246.      * <ul>
  247.      * <li>2221xx - 2720xx (16)</li>
  248.      * <li>51xxx - 55xxx (16)</li>
  249.      * </ul>
  250.      */
  251.     private static final RegexValidator MASTERCARD_REGEX = new RegexValidator(
  252.             "^(5[1-5]\\d{14})$",   // 51 - 55 (pre Oct 2016)
  253.             // valid from October 2016
  254.             "^(2221\\d{12})$",     // 222100 - 222199
  255.             "^(222[2-9]\\d{12})$", // 222200 - 222999
  256.             "^(22[3-9]\\d{13})$",  // 223000 - 229999
  257.             "^(2[3-6]\\d{14})$",   // 230000 - 269999
  258.             "^(27[01]\\d{13})$",   // 270000 - 271999
  259.             "^(2720\\d{12})$"      // 272000 - 272099
  260.         );

  262.     /** Mastercard Card Validator */
  263.     public static final CodeValidator MASTERCARD_VALIDATOR = new CodeValidator(MASTERCARD_REGEX, LUHN_VALIDATOR);

  265.     /**
  266.      * Mastercard Card Validator (pre Oct 2016)
  267.      * @deprecated for use until Oct 2016 only
  268.      */
  269.     @Deprecated
  270.     public static final CodeValidator MASTERCARD_VALIDATOR_PRE_OCT2016 = new CodeValidator("^(5[1-5]\\d{14})$", LUHN_VALIDATOR);

  272.     /**
  273.      * Visa Card Validator
  274.      * <p>
  275.      * 4xxxxx (13 or 16)
  276.      * </p>
  277.      */
  278.     public static final CodeValidator VISA_VALIDATOR = new CodeValidator("^(4)(\\d{12}|\\d{15})$", LUHN_VALIDATOR);

  280.     /**
  281.      * VPay (Visa) Card Validator
  282.      * <p>
  283.      * 4xxxxx (13-19)
  284.      * </p>
  285.      * @since 1.5.0
  286.      */
  287.     public static final CodeValidator VPAY_VALIDATOR = new CodeValidator("^(4)(\\d{12,18})$", LUHN_VALIDATOR);

  289.     // package protected for unit test access
  290.     static CodeValidator createRangeValidator(final CreditCardRange[] creditCardRanges, final CheckDigit digitCheck) {
  291.         return new CodeValidator(
  292.                 // must be numeric (rest of validation is done later)
  293.                 new RegexValidator("(\\d+)") {
  294.                     private static final long serialVersionUID = 1L;
  295.                     private final transient CreditCardRange[] ccr = creditCardRanges.clone();

  297.                     @Override
  298.                     public boolean isValid(final String value) {
  299.                         return validate(value) != null;
  300.                     }

  302.                     @Override
  303.                     public String[] match(final String value) {
  304.                         return new String[] { validate(value) };
  305.                     }

  307.                     @Override
  308.                     // must return full string
  309.                     public String validate(final String value) {
  310.                         if (super.match(value) != null) {
  311.                             final int length = value.length();
  312.                             for (final CreditCardRange range : ccr) {
  313.                                 if (validLength(length, range)) {
  314.                                     if (range.high == null) { // single prefix only
  315.                                         if (value.startsWith(range.low)) {
  316.                                             return value;
  317.                                         }
  318.                                     } else if (range.low.compareTo(value) <= 0 // no need to trim value here
  319.                                             &&
  320.                                     // here we have to ignore digits beyond the prefix
  321.                                             range.high.compareTo(value.substring(0, range.high.length())) >= 0) {
  322.                                         return value;
  323.                                     }
  324.                                 }
  325.                             }
  326.                         }
  327.                         return null;
  328.                     }
  329.                 }, digitCheck);
  330.     }

  332.     /**
  333.      * Creates a new generic CreditCardValidator which validates the syntax and check digit only.
  334.      * Does not check the Issuer Identification Number (IIN)
  335.      *
  336.      * @return the validator
  337.      * @since 1.6
  338.      */
  339.     public static CreditCardValidator genericCreditCardValidator() {
  340.         return genericCreditCardValidator(MIN_CC_LENGTH, MAX_CC_LENGTH);
  341.     }

  343.     /**
  344.      * Creates a new generic CreditCardValidator which validates the syntax and check digit only.
  345.      * Does not check the Issuer Identification Number (IIN)
  346.      *
  347.      * @param length exact length
  348.      * @return the validator
  349.      * @since 1.6
  350.      */
  351.     public static CreditCardValidator genericCreditCardValidator(final int length) {
  352.         return genericCreditCardValidator(length, length);
  353.     }

  355.     /**
  356.      * Creates a new generic CreditCardValidator which validates the syntax and check digit only.
  357.      * Does not check the Issuer Identification Number (IIN)
  358.      *
  359.      * @param minLen minimum allowed length
  360.      * @param maxLen maximum allowed length
  361.      * @return the validator
  362.      * @since 1.6
  363.      */
  364.     public static CreditCardValidator genericCreditCardValidator(final int minLen, final int maxLen) {
  365.         return new CreditCardValidator(new CodeValidator[] {new CodeValidator("(\\d+)", minLen, maxLen, LUHN_VALIDATOR)});
  366.     }

  368.     // package protected for unit test access
  369.     static boolean validLength(final int valueLength, final CreditCardRange range) {
  370.         if (range.lengths != null) {
  371.             for (final int length : range.lengths) {
  372.                 if (valueLength == length) {
  373.                     return true;
  374.                 }
  375.             }
  376.             return false;
  377.         }
  378.         return valueLength >= range.minLen && valueLength <= range.maxLen;
  379.     }

  381.     /**
  382.      * The CreditCardTypes that are allowed to pass validation.
  383.      */
  384.     private final List<CodeValidator> cardTypes = new ArrayList<>();

  386.     /**
  387.      * Constructs a new CreditCardValidator with default options.
  388.      * The default options are:
  389.      * AMEX, VISA, MASTERCARD and DISCOVER
  390.      */
  391.     public CreditCardValidator() {
  392.         this(AMEX + VISA + MASTERCARD + DISCOVER);
  393.     }

  395.     /**
  396.      * Constructs a new CreditCardValidator with the specified {@link CodeValidator}s.
  397.      * @param creditCardValidators Set of valid code validators
  398.      */
  399.     public CreditCardValidator(final CodeValidator[] creditCardValidators) {
  400.         if (creditCardValidators == null) {
  401.             throw new IllegalArgumentException("Card validators are missing");
  402.         }
  403.         Collections.addAll(cardTypes, creditCardValidators);
  404.     }

  406.     /**
  407.      * Constructs a new CreditCardValidator with the specified {@link CodeValidator}s
  408.      * and {@link CreditCardRange}s.
  409.      * <p>
  410.      * This can be used to combine predefined validators such as {@link #MASTERCARD_VALIDATOR}
  411.      * with additional validators using the simpler {@link CreditCardRange}s.
  412.      * @param creditCardValidators Set of valid code validators
  413.      * @param creditCardRanges Set of valid code validators
  414.      * @since 1.6
  415.      */
  416.     public CreditCardValidator(final CodeValidator[] creditCardValidators, final CreditCardRange[] creditCardRanges) {
  417.         if (creditCardValidators == null) {
  418.             throw new IllegalArgumentException("Card validators are missing");
  419.         }
  420.         if (creditCardRanges == null) {
  421.             throw new IllegalArgumentException("Card ranges are missing");
  422.         }
  423.         Collections.addAll(cardTypes, creditCardValidators);
  424.         Collections.addAll(cardTypes, createRangeValidator(creditCardRanges, LUHN_VALIDATOR));
  425.     }

  427.     /**
  428.      * Constructs a new CreditCardValidator with the specified {@link CreditCardRange}s.
  429.      * @param creditCardRanges Set of valid code validators
  430.      * @since 1.6
  431.      */
  432.     public CreditCardValidator(final CreditCardRange[] creditCardRanges) {
  433.         if (creditCardRanges == null) {
  434.             throw new IllegalArgumentException("Card ranges are missing");
  435.         }
  436.         Collections.addAll(cardTypes, createRangeValidator(creditCardRanges, LUHN_VALIDATOR));
  437.     }

  439.     /**
  440.      * Constructs a new CreditCardValidator with the specified options.
  441.      * @param options Pass in
  442.      * CreditCardValidator.VISA + CreditCardValidator.AMEX to specify that
  443.      * those are the only valid card types.
  444.      */
  445.     public CreditCardValidator(final long options) {
  446.         if (isOn(options, VISA)) {
  447.             this.cardTypes.add(VISA_VALIDATOR);
  448.         }

  450.         if (isOn(options, VPAY)) {
  451.             this.cardTypes.add(VPAY_VALIDATOR);
  452.         }

  454.         if (isOn(options, AMEX)) {
  455.             this.cardTypes.add(AMEX_VALIDATOR);
  456.         }

  458.         if (isOn(options, MASTERCARD)) {
  459.             this.cardTypes.add(MASTERCARD_VALIDATOR);
  460.         }

  462.         if (isOn(options, MASTERCARD_PRE_OCT2016)) {
  463.             this.cardTypes.add(MASTERCARD_VALIDATOR_PRE_OCT2016);
  464.         }

  466.         if (isOn(options, DISCOVER)) {
  467.             this.cardTypes.add(DISCOVER_VALIDATOR);
  468.         }

  470.         if (isOn(options, DINERS)) {
  471.             this.cardTypes.add(DINERS_VALIDATOR);
  472.         }
  473.     }

  475.     /**
  476.      * Tests whether the given flag is on.  If the flag is not a power of 2
  477.      * (ie. 3) this tests whether the combination of flags is on.
  478.      *
  479.      * @param options The options specified.
  480.      * @param flag Flag value to check.
  481.      *
  482.      * @return whether the specified flag value is on.
  483.      */
  484.     private boolean isOn(final long options, final long flag) {
  485.         return (options & flag) > 0;
  486.     }

  488.     /**
  489.      * Checks if the field is a valid credit card number.
  490.      * @param card The card number to validate.
  491.      * @return Whether the card number is valid.
  492.      */
  493.     public boolean isValid(final String card) {
  494.         if (GenericValidator.isBlankOrNull(card)) {
  495.             return false;
  496.         }
  497.         for (final CodeValidator cardType : cardTypes) {
  498.             if (cardType.isValid(card)) {
  499.                 return true;
  500.             }
  501.         }
  502.         return false;
  503.     }

  505.     /**
  506.      * Checks if the field is a valid credit card number.
  507.      * @param card The card number to validate.
  508.      * @return The card number if valid or {@code null}
  509.      * if invalid.
  510.      */
  511.     public Object validate(final String card) {
  512.         if (GenericValidator.isBlankOrNull(card)) {
  513.             return null;
  514.         }
  515.         Object result = null;
  516.         for (final CodeValidator cardType : cardTypes) {
  517.             result = cardType.validate(card);
  518.             if (result != null) {
  519.                 return result;
  520.             }
  521.         }
  522.         return null;

  524.     }

  526. }
Created with JaCoCo 0.8.12.202403310830