Module com.aoapps.payments.api
Package com.aoapps.payments

Class CreditCard

java.lang.Object
com.aoapps.payments.CreditCard
All Implemented Interfaces:
Cloneable
public class CreditCard extends Object implements Cloneable
Encapsulates the credit card details that are sent to the bank, retrieved from the database, or manipulated in any way. The credit card details include card numbers and related billing address details.

If this card is retrieved from an encrypted/protected source, not all the information will necessarily be available.

Author:
AO Industries, Inc.

  • Field Details

    • MASK_START_DIGITS

      public static final int MASK_START_DIGITS
      The maximum number of starting digits kept when masked.
      See Also:

    • MASK_END_DIGITS

      public static final int MASK_END_DIGITS
      The maximum number of ending digits kept when masked.
      See Also:

    • MASK_CHARACTER

      public static final char MASK_CHARACTER
      The character used representing a masked digit.
      See Also:

    • UNKNOWN_DIGIT

      public static final char UNKNOWN_DIGIT
      The character used for an unknown digits. Unknown digits would not be masked if available, but are simply not available. This is used when converting from card type + last4 back to a masked card number. In a future version of the API, when both card type and last4 are stored, this mechanism will be unnecessary.
      See Also:

    • UNKNOWN_MIDDLE

      public static final char UNKNOWN_MIDDLE
      When the number of digits is unknown, such as generating a possible masked card number from type + last4, this can be used as a filler between beginning and end of the card number.
      See Also:

    • UNKNOWN_EXPIRATION_MONTH

      public static final byte UNKNOWN_EXPIRATION_MONTH
      Value used to represent an unknown expiration month.
      See Also:

    • UNKNOWN_EXPRIATION_MONTH

      @Deprecated(forRemoval=true) public static final byte UNKNOWN_EXPRIATION_MONTH
      Deprecated, for removal: This API element is subject to removal in a future version.
      Please use UNKNOWN_EXPIRATION_MONTH instead.
      Value used to represent an unknown expiration month.
      See Also:

    • UNKNOWN_EXPIRATION_YEAR

      public static final short UNKNOWN_EXPIRATION_YEAR
      Value used to represent an unknown expiration year.
      See Also:

    • UNKNOWN_EXPRIATION_YEAR

      @Deprecated(forRemoval=true) public static final short UNKNOWN_EXPRIATION_YEAR
      Deprecated, for removal: This API element is subject to removal in a future version.
      Please use UNKNOWN_EXPIRATION_YEAR instead.
      Value used to represent an unknown expiration year.
      See Also:

    • MIN_EXPIRATION_YEAR

      public static final short MIN_EXPIRATION_YEAR
      The minimum expected expiration year.
      See Also:

    • EXPIRATION_YEARS_FUTURE

      public static final short EXPIRATION_YEARS_FUTURE
      The maximum number of years in the future expected for an expiration year, inclusive.
      1. Stripe Dashboard allows +19 years
      2. Stack Overflow - Maximum Year in Expiry Date of Credit Card indicates +20 years for Amazon
      See Also:

    • CARD_NUMBER_DISPLAY_PREFIX

      public static final String CARD_NUMBER_DISPLAY_PREFIX
      The prefix used for getCardNumberDisplay(java.lang.String).
      See Also:

    • EXPIRATION_DISPLAY_SEPARATOR

      public static final String EXPIRATION_DISPLAY_SEPARATOR
      The middle separator used for getExpirationDisplay(java.lang.Byte, java.lang.Short).
      See Also:

  • Constructor Details

  • Method Details

    • maskCreditCardNumber

      public static String maskCreditCardNumber(String cardNumber)
      Only keeps the first MASK_START_DIGITS and last MASK_END_DIGITS digits of a card number after trimming. Other digits are replaced with MASK_CHARACTER. All non-digit characters are left intact. If the number is null, returns an empty string.

    • numbersOnly

      public static String numbersOnly(String value, boolean allowUnknownDigit)
      Gets the numbers out of a String.
      Parameters:
      value - the value to extract numbers from
      allowUnknownDigit - selects inclusion of UNKNOWN_DIGIT in the result

    • numbersOnly

      public static String numbersOnly(String value)
      Gets the numbers out of a String, not including any UNKNOWN_DIGIT.

    • getCardNumberDisplay

      public static String getCardNumberDisplay(String cardNumber)
      See CARD_NUMBER_DISPLAY_PREFIX and getCardNumberDisplay().

    • validateExpirationMonth

      public static byte validateExpirationMonth(byte expirationMonth, boolean allowUnknownDate) throws IllegalArgumentException
      Validates an expiration month.
      Throws:
      IllegalArgumentException

    • validateExpirationYear

      public static short validateExpirationYear(short expirationYear, boolean allowUnknownDate) throws IllegalArgumentException
      Validates an expiration year.
      Throws:
      IllegalArgumentException

    • getExpirationDateMMYY

      public static String getExpirationDateMMYY(byte expirationMonth, short expirationYear, boolean allowUnknownDate) throws IllegalArgumentException
      Gets an expiration date in MMYY format.
      Parameters:
      expirationMonth - the month or UNKNOWN_EXPIRATION_MONTH when unknown
      expirationYear - the year or UNKNOWN_EXPIRATION_YEAR when unknown
      allowUnknownDate - selects inclusion of UNKNOWN_DIGIT in the result
      Throws:
      IllegalArgumentException - if invalid date

    • getExpirationDateMMYY

      @Deprecated(forRemoval=true) public static String getExpirationDateMMYY(byte expirationMonth, short expirationYear)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Please use getExpirationDateMMYY(byte, short, boolean) allowing for unknown expirations
      Gets an expiration date in MMYY format, not including any UNKNOWN_DIGIT.

    • getExpirationDisplay

      public static String getExpirationDisplay(Byte expirationMonth, Short expirationYear) throws IllegalArgumentException
      Gets the expiration display in "MM / YYYY" format or null when both month and year are unknown.
      Throws:
      IllegalArgumentException - if invalid date
      See Also:

    • getFullName

      public static String getFullName(String firstName, String lastName)
      Combines the first and last names into a single name String.

    • clone

      public CreditCard clone() throws CloneNotSupportedException
      Overrides:
      clone in class Object
      Throws:
      CloneNotSupportedException

    • getPersistenceUniqueId

      public String getPersistenceUniqueId()
      Gets the persistence unique identifier.

    • setPersistenceUniqueId

      public void setPersistenceUniqueId(String persistenceUniqueId)
      Sets the persistence unique identifier.

    • getPrincipalName

      public String getPrincipalName()
      Gets the name of the principal who added the card.

    • setPrincipalName

      public void setPrincipalName(String principalName)
      Sets the name of the principal who added the card.

    • getGroupName

      public String getGroupName()
      Gets the name of the group this card belongs to.

    • setGroupName

      public void setGroupName(String groupName)
      Sets the name of the group this card belongs to.

    • getProviderId

      public String getProviderId()
      Gets the id of the merchant services provider that is storing this card.

    • setProviderId

      public void setProviderId(String providerId)
      Sets the id of the merchant services provider that is storing this card.

    • getProviderUniqueId

      public String getProviderUniqueId()
      Gets the provider-specific unique id representing this card.

    • setProviderUniqueId

      public void setProviderUniqueId(String providerUniqueId)
      Sets the provider-specific unique id representing this card.

    • getCardNumber

      public String getCardNumber()
      Gets the full credit card number. This may return null if the full card number is not available.

    • setCardNumber

      public void setCardNumber(String cardNumber)
      Trims and sets the full credit card number. Also sets the masked card number if cardNumber is not null.
      Throws:
      IllegalArgumentException - if invalid credit card number

    • getMaskedCardNumber

      public String getMaskedCardNumber()
      Gets the masked card number. This contains the first two and last four digits of the card number. This value will usually be available while the card number will is only available for new transactions.

    • setMaskedCardNumber

      public void setMaskedCardNumber(String maskedCardNumber)
      Sets the masked card number.

    • getCardNumberDisplay

      public String getCardNumberDisplay()
      See getCardNumberDisplay(java.lang.String).

    • getExpirationMonth

      public byte getExpirationMonth()
      Gets the expiration month, where 1 is January and 12 is December.
      See Also:

    • setExpirationMonth

      public void setExpirationMonth(byte expirationMonth)
      Sets the expiration month, where 1 is January and 12 is December.
      Throws:
      IllegalArgumentException - if out of range.
      See Also:

    • getExpirationYear

      public short getExpirationYear()
      Gets the expiration year, such as 2007.
      See Also:

    • setExpirationYear

      public void setExpirationYear(short expirationYear)
      Sets the expiration year, such as 2007. It also accepts values 0 <= year <= 99. These values will be automatically added to the current century.
      Throws:
      IllegalArgumentException - if the resolved year is < MIN_EXPIRATION_YEAR or > (current year + EXPIRATION_YEARS_FUTURE)
      See Also:

    • getExpirationDateMMYY

      public String getExpirationDateMMYY(boolean allowUnknownDate)
      Gets the expiration date in MMYY format, not including any UNKNOWN_DIGIT.
      Parameters:
      allowUnknownDate - selects inclusion of UNKNOWN_DIGIT in the result
      Throws:
      IllegalArgumentException - if invalid date

    • getExpirationDateMMYY

      @Deprecated(forRemoval=true) public String getExpirationDateMMYY()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Please use getExpirationDateMMYY(boolean) allowing for unknown expirations
      Gets the expiration date in MMYY format, not including any UNKNOWN_DIGIT.
      Throws:
      IllegalArgumentException - if invalid date

    • getExpirationDisplay

      public String getExpirationDisplay()
      See getExpirationDisplay(java.lang.Byte, java.lang.Short).

    • getCardCode

      public String getCardCode()
      Gets the three or four digit card security code. This value is never stored and is therefore only available for a new card.

    • validateCardCode

      public static String validateCardCode(String cardCode) throws LocalizedIllegalArgumentException
      Checks a card code format.
      Parameters:
      cardCode - The card code to check
      Returns:
      The card code to use
      Throws:
      LocalizedIllegalArgumentException - if card code invalid

    • setCardCode

      public void setCardCode(String cardCode) throws LocalizedIllegalArgumentException
      Trims and sets the three or four digit card security code.
      Throws:
      IllegalArgumentException - if the value is not either null or purely digits (after trimming) and 3 or 4 digits long.
      LocalizedIllegalArgumentException

    • getFirstName

      public String getFirstName()
      Gets the first name of the card holder.

    • setFirstName

      public void setFirstName(String firstName)
      Trims and sets the first name of the card holder.

    • getLastName

      public String getLastName()
      Gets the last name of the card holder.

    • setLastName

      public void setLastName(String lastName)
      Trims and sets the last name of the card holder.

    • getCompanyName

      public String getCompanyName()
      Gets the company name of the card holder.

    • setCompanyName

      public void setCompanyName(String companyName)
      Trims and sets the company name of the card holder.

    • getEmail

      public String getEmail()
      Gets the card holder's email address.

    • setEmail

      public void setEmail(String email)
      Trims and sets the card holder's email address.
      Throws:
      IllegalArgumentException - if the address does is not in the proper format

    • getPhone

      public String getPhone()
      Gets the card holder's telephone number.

    • setPhone

      public void setPhone(String phone)
      Trims and sets the card holder's telephone number.

    • getFax

      public String getFax()
      Gets the card holder's fax number.

    • setFax

      public void setFax(String fax)
      Trims and sets the card holder's fax number.

    • getCustomerId

      public String getCustomerId()
      Gets the merchant-specific unique customer ID.

    • setCustomerId

      public void setCustomerId(String customerId)
      Sets the merchant-specific unique customer ID.

    • getCustomerTaxId

      public String getCustomerTaxId()
      Gets the customer SSN or Tax ID.

    • setCustomerTaxId

      public void setCustomerTaxId(String customerTaxId)
      Trims and sets the customer SSN or Tax ID, removes any spaces and hyphens.
      Throws:
      IllegalArgumentException - if not a nine digit number after trimming.

    • getStreetAddress1

      public String getStreetAddress1()
      Gets the card holder's street address (first line).

    • setStreetAddress1

      public void setStreetAddress1(String streetAddress1)
      Trims and sets the card holder's street address (first line).

    • getStreetAddress2

      public String getStreetAddress2()
      Gets the card holder's street address (second line).

    • setStreetAddress2

      public void setStreetAddress2(String streetAddress2)
      Trims and sets the card holder's street address (second line).

    • getCity

      public String getCity()
      Gets the card holder's city.

    • setCity

      public void setCity(String city)
      Trims and sets the card holder's city.

    • getState

      public String getState()
      Gets the card holder's state/province/prefecture.

    • setState

      public void setState(String state)
      Trims and sets the card holder's state/province/prefecture.

    • getPostalCode

      public String getPostalCode()
      Gets the card holder's postal code.

    • setPostalCode

      public void setPostalCode(String postalCode)
      Trims and sets the card holder's postal code.

    • getCountryCode

      public String getCountryCode()
      Gets the card holder's two-digit ISO 3166-1 alpha-2 country code.

      See https://wikipedia.org/wiki/ISO_3166-1_alpha-2

    • setCountryCode

      public void setCountryCode(String countryCode)
      Trims, converts to upper case, and sets the card holder's two-digit ISO 3166-1 alpha-2 country code.

      See https://wikipedia.org/wiki/ISO_3166-1_alpha-2

      Throws:
      IllegalArgumentException - if not a two-character code (after trimming).

    • getComments

      public String getComments()
      Gets the comments associated with this card.

    • setComments

      public void setComments(String comments)
      Sets the comments associated with this card.