File: YACC.txt

YACC: yet another Credit Card Validation class

Summary
This class provides a single source of validating a credit card number. The
class validates:-
* That the number is valid, checking it against the Luhn modulo 10 check.
* That the Valid From date (if supplied) is either valid, an issue no of 2
digits or null.
* That the Valid To is valid.
The class will return a text string identifying the card type, such as
Mastercard, or Visa

Package contents
cls_CreditCard.php	-implements the class credit_card
testccclass.php	-test container to prove the class works
YACC.pdf	-this document

Background
This class is based on class already published on PHPClasses; sadly I do not
have the original authors name to recognise their contribution. The reason
that this class was written was to overcome a problem on an existing site.
The issue related to the different types of card in circulation and the
failings in the card merchant service providers systems. In effect they (the
bank merchant service provider) were unable (or unwilling) to identify cards
which the site owners merchant agreement excluded them from accepting. It was
triggered by the bank providing an authorisation code on a cardholder not
present (CNP) transaction which they later tried to reject claiming the
website owner should have known, was not an acceptable card, despite the banks
inability or unwillingness to supply information that could identify rogue
cards. The bank intended my customer to carry the cost of the transaction, and
any future transactions that they authorised and later decided to renege on
(it should go without saying that it couldnt possibly be the banks fault, and
therefore someone else should pay for the banks failings).

I also experienced problems with the Luhn validation method in the original
class; it didnt seem to work as I expected it to. It could well be that it
was my fault, rather than the original method, but I felt unable to run with
the existing implementation.

The card types and names reflect the fact that the Author is UK based, and
therefore the card names are the names in use in the UK which may or may not
be the same as elsewhere

Usage
We use the class to perform the following actions:-
1) Check the card number is valid  ie passes the Luhn modulo 10 check
2) To identify the card type from the supplied number.
3) Check the Valid From date is less than or equal to today
   (expressed as mm/yy ie April 2003 is 04/03)
4) Check the Valid To date is greater than or equal to today
   (expressed as mm/yy ie June 2007 is 06/07)
* Therefore by definition you cannot have a valid from date that is greater
  than the valid to date. If that were to happen either or both will report
  an error.

Note:
* The Valid From date is not provided on all cards, therefore null is valid.
  If you know that you will never handle a null valid from date then it can
  be safely removed.
* The valid from date also acts as an Issue No placeholder for some cards
  (eg bank ATM / EFT [electronic funds transfer] cards such as Switch. There
  is however a complication in that not all Switch cards (for example) have
  an Issue number (some have a Valid From date).
* At present most of the sites are also mandated to require a telephone
  number, and Cardholders name (if the name is different to the person
  receiving the goods). I would expect you to implement those and any other
  such checks within the main validation section, not in the class itself.
i. As yet the only telephone validation we do is to ensure the number is
   numeric and at least 11 digits, beyond that I am not aware of any viable
   validation algorithm.
ii. The bank requires the phone number to be a conventional phone number
    (IE not a mobile / handy / cellular). Although this can be done for
    UK mobiles (ie those starting with 07, (international +44 7) we ignore
    that element of the banks requirements.

Implementation
After including the class in the target script:-
Include (..<pathtoclass>/cls_CreditCard.php);
Call the class:-
<$fieldname>=credit_card::check(<$creditcard>,<$validfrom>,<$validto);
Example:	$CCData= credit_card::check($CCNo,$VFr,$VTo);
where
<$fieldname>	is the holder of class functions return variable
<$creditcard>	is the variable holding the credit card number to be checked. This can be either all numeric or including the spacing typed in by the user, the class strips out any non numeric digits in the supplied number.
<$validfrom>    is the variable containing the Valid From in the form mm/yy
                OR the Issue No, or nothing (ie NULL).
<$validto>      is the variable containing the Valid To in the form mm/yy.

the credit_card::check function returns a parameter array containing the
following:-
<$fieldname>[Valid]	indicates if the card passes the luhn modulo 10 check
<$fieldname>[CanAccept] indicates if the card is acceptable to your
                        installation.
<$fieldname>[Index] 	indicates the card type, see the class for details
                        - count starts from 11,
                        unless it is unknown, in which case it is 0.
<$fieldname>[Type]	returns a text string identifying the card
                        eg VISA, Switch / Maestro etc....
<$fieldname>[VFr]	returns TRUE is there is an error with the Valid From
                        / Issue No, else returns FALSE
<$fieldname>[VTo]	returns TRUE is there is an error with the Valid To,
                        else returns FALSE

For  legacy reasons the [Type] parameter starts from 11, or is 0 if invalid
(lower numbers were used to identify other payment types. We use numbers
below 10 to identify non card based transactions.

It is possible for the card number to be valid ie [Valid] = TRUE, and the
[CanAccept] to be false and / or the [Type] to be 0, and conversely for the
card to be identified correctly but the number fails validation. This will
occur where the card is one of the types you have specified as unable to
accept OR a type the class does not know about. IE the class may need
updating

The minimum required to use the class is to check that the card number is
valid ([Valid] == TRUE). It is your choice if you implement the other fields,
presumably if you wish to implement this class then you do. We check that the
card type [Index] matches the card index identified by the customer on the
site. IE we get the visitor to select the card they are using from a
predetermined list, and validate the [Index] matches the selected card.  We
use the [Type] for reporting purposes (either on error OR for final receipt).
For example the final screen of the transaction identifies the payment method
as being Payment method: by VISA Debit card.

You can also call
Credit_card::clean_no(<$creditcard>) which will return the credit card
stripped of any non numeric elements. The other functions can be called in the
class, but the intended gateway to the class is:
credit_card::check(<$creditcard>,<$validfrom>,<$validto);

Testing this class
A php script has been included in the documentation (testccclass.php), which
implements the credit_card::check method. Apologies for failings in style, I
admit to being a PHP non expert. The test script expects the class to be in
a child directory ../incfiles  you will almost certainly need to modify this
path to point to the directory containing the class file. Try it with as many
cards a you feel comfortable with.

Problems with this class
If you experience any problems with the class please let me know by
email:matthew.heald@virgin.net

Licence
The code is provided as is, there is no claim to copyright or restriction of
use, nor is there any explicit warranty or guarantees. I would recommend that
you complete as many exhaustive checks as required to satisfy yourself that
the code is suitable for your purpose. I cant provide guarantees, or any form
of redress (legal, financial or otherwise) should it fail to meet your
requirements, however it is used in several web sites with no adverse
comments. It is provided on the basis that it may help other PHP developers.

Initial Testing
The class was developed on a an SUSE Linux 8.2 Professional, running
PHP 4.2.2 as a module.
phpinfo identifies the kernel as knuth 2.4.19 dated Sept 11, 2002,
the PHP version is dated Sept 12, 2002.
It has been successfully tested (and runs) on several production servers, all
running PHP 4.

Final Comment
This is the first public PHP class I have released. I do not claim to be an
expert in PHP. I have used structures and conventions I am familiar with. The
coding style happens to be one I am comfortable with, others may disagree. I
am not going to throw my toys out of the pram if someone wants to rephrase
the class in a manner that perceived to be more conventional. Given that the
class is unlikely to be used in a time critical process I feel that
reliability and legibility is better than the most tightly optimised class.

References
Document identifying valid credit card number ranges as at Sept 2003
  http://www.barclaycardmerchantservices.co.uk/info_centre/operational/pdf/binranges.pdf
URL explaining the implementation of the Luhn Modulo 10 check URL:
  http://merriampark.com/anatomycc.htm