documentation/manual/en/module_specs/Zend_Validate-CreditCard.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.validate.set.creditcard">
   4     <title>CreditCard</title>
   5
   6     <para>
   7         <classname>Zend_Validate_CreditCard</classname> allows you to validate if a given value
   8         could be a credit card number.
   9     </para>
  10
  11     <para>
  12         A creditcard contains several items of metadata, including a hologram, account number, logo,
  13         expiration date, security code and the card holder name. The algorithms for verifying the
  14         combination of metadata are only known to the issuing company, and should be verified with
  15         them for purposes of payment. However, it's often useful to know whether or not a given
  16         number actually falls within the ranges of possible numbers <emphasis>prior</emphasis> to
  17         performing such verification, and, as such, <classname>Zend_Validate_CreditCard</classname>
  18         simply verifies that the credit card number provided is well-formed.
  19     </para>
  20
  21     <para>
  22         For those cases where you have a service that can perform comprehensive verification,
  23         <classname>Zend_Validate_CreditCard</classname> also provides the ability to attach a
  24         service callback to trigger once the credit card number has been deemed valid; this callback
  25         will then be triggered, and its return value will determine overall validity.
  26     </para>
  27
  28     <para>
  29         The following issuing institutes are accepted:
  30     </para>
  31
  32     <itemizedlist>
  33         <listitem>
  34             <para>
  35                 <emphasis>American Express</emphasis>
  36             </para>
  37
  38             <para>
  39                 <emphasis>China UnionPay</emphasis>
  40             </para>
  41
  42             <para>
  43                 <emphasis>Diners Club Card Blanche</emphasis>
  44             </para>
  45
  46             <para>
  47                 <emphasis>Diners Club International</emphasis>
  48             </para>
  49
  50             <para>
  51                 <emphasis>Diners Club US &amp; Canada</emphasis>
  52             </para>
  53
  54             <para>
  55                 <emphasis>Discover Card</emphasis>
  56             </para>
  57
  58             <para>
  59                 <emphasis>JCB</emphasis>
  60             </para>
  61
  62             <para>
  63                 <emphasis>Laser</emphasis>
  64             </para>
  65
  66             <para>
  67                 <emphasis>Maestro</emphasis>
  68             </para>
  69
  70             <para>
  71                 <emphasis>MasterCard</emphasis>
  72             </para>
  73
  74             <para>
  75                 <emphasis>Solo</emphasis>
  76             </para>
  77
  78             <para>
  79                 <emphasis>Visa</emphasis>
  80             </para>
  81
  82             <para>
  83                 <emphasis>Visa Electron</emphasis>
  84             </para>
  85         </listitem>
  86     </itemizedlist>
  87
  88     <note>
  89         <title>Invalid institutes</title>
  90
  91         <para>
  92             The institutes <emphasis>Bankcard</emphasis> and <emphasis>Diners Club
  93                 enRoute</emphasis> do not exist anymore. Therefore they are treated as invalid.
  94         </para>
  95
  96         <para>
  97             <emphasis>Switch</emphasis> has been rebranded to <emphasis>Visa</emphasis> and is
  98             therefore also treated as invalid.
  99         </para>
 100     </note>
 101
 102     <sect3 id="zend.validate.set.creditcard.options">
 103         <title>Supported options for Zend_Validate_CreditCard</title>
 104
 105         <para>
 106             The following options are supported for <classname>Zend_Validate_CreditCard</classname>:
 107         </para>
 108
 109         <itemizedlist>
 110             <listitem>
 111                 <para>
 112                     <emphasis><property>service</property></emphasis>: A callback to an online
 113                     service which will additionally be used for the validation.
 114                 </para>
 115             </listitem>
 116
 117             <listitem>
 118                 <para>
 119                     <emphasis><property>type</property></emphasis>: The type of creditcard which
 120                     will be validated. See the below list of institutes for details.
 121                 </para>
 122             </listitem>
 123         </itemizedlist>
 124     </sect3>
 125
 126     <sect3 id="zend.validate.set.creditcard.basic">
 127         <title>Basic usage</title>
 128
 129         <para>
 130             There are several credit card institutes which can be validated by
 131             <classname>Zend_Validate_CreditCard</classname>. Per default, all known institutes will
 132             be accepted. See the folowing example:
 133         </para>
 134
 135         <programlisting language="php"><![CDATA[
 136 $valid = new Zend_Validate_CreditCard();
 137 if ($valid->isValid($input)) {
 138     // input appears to be valid
 139 } else {
 140     // input is invalid
 141 }
 142 ]]></programlisting>
 143
 144         <para>
 145             The above example would validate against all known credit card institutes.
 146         </para>
 147     </sect3>
 148
 149     <sect3 id="zend.validate.set.creditcard.institute">
 150         <title>Accepting defined credit cards</title>
 151
 152         <para>
 153             Sometimes it is necessary to accept only defined credit card institutes instead of all;
 154             e.g., when you have a webshop which accepts only Visa and American Express cards.
 155             <classname>Zend_Validate_CreditCard</classname> allows you to do exactly this by
 156             limiting it to exactly these institutes.
 157         </para>
 158
 159         <para>
 160             To use a limitation you can either provide specific institutes at initiation, or
 161             afterwards by using <methodname>setType()</methodname>. Each can take several arguments.
 162         </para>
 163
 164         <para>
 165             You can provide a single institute:
 166         </para>
 167
 168         <programlisting language="php"><![CDATA[
 169 $valid = new Zend_Validate_CreditCard(
 170     Zend_Validate_CreditCard::AMERICAN_EXPRESS
 171 );
 172 ]]></programlisting>
 173
 174         <para>
 175             When you want to allow multiple institutes, then you can provide them as array:
 176         </para>
 177
 178         <programlisting language="php"><![CDATA[
 179 $valid = new Zend_Validate_CreditCard(array(
 180     Zend_Validate_CreditCard::AMERICAN_EXPRESS,
 181     Zend_Validate_CreditCard::VISA
 182 ));
 183 ]]></programlisting>
 184
 185         <para>
 186             And as with all validators, you can also pass an associative array of options or an
 187             instance of <classname>Zend_Config</classname>. In this case you have to provide the
 188             institutes with the <property>type</property> array key as simulated here:
 189         </para>
 190
 191         <programlisting language="php"><![CDATA[
 192 $valid = new Zend_Validate_CreditCard(array(
 193     'type' => array(Zend_Validate_CreditCard::AMERICAN_EXPRESS)
 194 ));
 195 ]]></programlisting>
 196
 197         <table id="zend.validate.set.creditcard.institute.table">
 198             <title>Constants for credit card institutes</title>
 199
 200             <tgroup cols="2">
 201                 <thead>
 202                     <row>
 203                         <entry>Institute</entry>
 204                         <entry>Constant</entry>
 205                     </row>
 206                 </thead>
 207
 208                 <tbody>
 209                     <row>
 210                         <entry><emphasis>American Express</emphasis></entry>
 211                         <entry><constant>AMERICAN_EXPRESS</constant></entry>
 212                     </row>
 213
 214                     <row>
 215                         <entry><emphasis>China UnionPay</emphasis></entry>
 216                         <entry><constant>UNIONPAY</constant></entry>
 217                     </row>
 218
 219                     <row>
 220                         <entry><emphasis>Diners Club Card Blanche</emphasis></entry>
 221                         <entry><constant>DINERS_CLUB</constant></entry>
 222                     </row>
 223
 224                     <row>
 225                         <entry><emphasis>Diners Club International</emphasis></entry>
 226                         <entry><constant>DINERS_CLUB</constant></entry>
 227                     </row>
 228
 229                     <row>
 230                         <entry><emphasis>Diners Club US &amp; Canada</emphasis></entry>
 231                         <entry><constant>DINERS_CLUB_US</constant></entry>
 232                     </row>
 233
 234                     <row>
 235                         <entry><emphasis>Discover Card</emphasis></entry>
 236                         <entry><constant>DISCOVER</constant></entry>
 237                     </row>
 238
 239                     <row>
 240                         <entry><emphasis>JCB</emphasis></entry>
 241                         <entry><constant>JCB</constant></entry>
 242                     </row>
 243
 244                     <row>
 245                         <entry><emphasis>Laser</emphasis></entry>
 246                         <entry><constant>LASER</constant></entry>
 247                     </row>
 248
 249                     <row>
 250                         <entry><emphasis>Maestro</emphasis></entry>
 251                         <entry><constant>MAESTRO</constant></entry>
 252                     </row>
 253
 254                     <row>
 255                         <entry><emphasis>MasterCard</emphasis></entry>
 256                         <entry><constant>MASTERCARD</constant></entry>
 257                     </row>
 258
 259                     <row>
 260                         <entry><emphasis>Solo</emphasis></entry>
 261                         <entry><constant>SOLO</constant></entry>
 262                     </row>
 263
 264                     <row>
 265                         <entry><emphasis>Visa</emphasis></entry>
 266                         <entry><constant>VISA</constant></entry>
 267                     </row>
 268
 269                     <row>
 270                         <entry><emphasis>Visa Electron</emphasis></entry>
 271                         <entry><constant>VISA</constant></entry>
 272                     </row>
 273                 </tbody>
 274             </tgroup>
 275         </table>
 276
 277         <para>
 278             You can also set or add institutes afterward instantiation by using the methods
 279             <methodname>setType()</methodname>, <methodname>addType()</methodname> and
 280             <methodname>getType()</methodname>.
 281         </para>
 282
 283         <programlisting language="php"><![CDATA[
 284 $valid = new Zend_Validate_CreditCard();
 285 $valid->setType(array(
 286     Zend_Validate_CreditCard::AMERICAN_EXPRESS,
 287     Zend_Validate_CreditCard::VISA
 288 ));
 289 ]]></programlisting>
 290
 291         <note>
 292             <title>Default institute</title>
 293
 294             <para>
 295                 When no institute is given at initiation then <constant>ALL</constant> will be
 296                 used, which sets all institutes at once.
 297             </para>
 298
 299             <para>
 300                 In this case the usage of <methodname>addType()</methodname> is useless because all
 301                 institutes are already added.
 302             </para>
 303         </note>
 304     </sect3>
 305
 306     <sect3 id="zend.validate.set.creditcard.servicecheck">
 307         <title>Validation by using foreign APIs</title>
 308
 309         <para>
 310             As said before <classname>Zend_Validate_CreditCard</classname> will only validate
 311             the credit card number. Fortunately, some institutes provide online
 312             <acronym>API</acronym>s which can validate a credit card number by using algorithms
 313             which are not available to the public. Most of these services are paid services.
 314             Therefore, this check is deactivated per default.
 315         </para>
 316
 317         <para>
 318             When you have access to such an <acronym>API</acronym>, then you can use it as an addon
 319             for <classname>Zend_Validate_CreditCard</classname> and increase the security of the
 320             validation.
 321         </para>
 322
 323         <para>
 324             To do so, you simply need to give a callback which will be called when the generic
 325             validation has passed. This prevents the <acronym>API</acronym> from being called
 326             for invalid numbers, which increases the performance of the application.
 327         </para>
 328
 329         <para>
 330             <methodname>setService()</methodname> sets a new service, and
 331             <methodname>getService()</methodname> returns the set service. As a configuration
 332             option,
 333             you can give the array key '<property>service</property>' at initiation. For details
 334             about possible options take a look into <link
 335                 linkend="zend.validate.set.callback">Callback</link>.
 336         </para>
 337
 338         <programlisting language="php"><![CDATA[
 339 // Your service class
 340 class CcService
 341 {
 342     public function checkOnline($cardnumber, $types)
 343     {
 344         // some online validation
 345     }
 346 }
 347
 348 // The validation
 349 $service = new CcService();
 350 $valid   = new Zend_Validate_CreditCard(Zend_Validate_CreditCard::VISA);
 351 $valid->setService(array($service, 'checkOnline'));
 352 ]]></programlisting>
 353
 354         <para>
 355             As you can see the callback method will be called with the creditcard number as the
 356             first parameter, and the accepted types as the second parameter.
 357         </para>
 358     </sect3>
 359 </sect2>
 360 <!--
 361 vim:se ts=4 sw=4 et:
 362 -->