FS/FS/payinfo_Mixin.pm

   1 package FS::payinfo_Mixin;
   2
   3 use strict;
   4 use Business::CreditCard;
   5 use FS::payby;
   6 use FS::Record qw(qsearch);
   7
   8 use vars qw($ignore_masked_payinfo);
   9
  10 =head1 NAME
  11
  12 FS::payinfo_Mixin - Mixin class for records in tables that contain payinfo.
  13
  14 =head1 SYNOPSIS
  15
  16 package FS::some_table;
  17 use vars qw(@ISA);
  18 @ISA = qw( FS::payinfo_Mixin FS::Record );
  19
  20 =head1 DESCRIPTION
  21
  22 This is a mixin class for records that contain payinfo.
  23
  24 =head1 FIELDS
  25
  26 =over 4
  27
  28 =item payby
  29
  30 The following payment types (payby) are supported:
  31
  32 For Customers (cust_main):
  33 'CARD' (credit card - automatic), 'DCRD' (credit card - on-demand),
  34 'CHEK' (electronic check - automatic), 'DCHK' (electronic check - on-demand),
  35 'LECB' (Phone bill billing), 'BILL' (billing), 'COMP' (free), or
  36 'PREPAY' (special billing type: applies a credit and sets billing type to I<BILL> - see L<FS::prepay_credit>)
  37
  38 For Refunds (cust_refund):
  39 'CARD' (credit cards), 'CHEK' (electronic check/ACH),
  40 'LECB' (Phone bill billing), 'BILL' (billing), 'CASH' (cash),
  41 'WEST' (Western Union), 'MCRD' (Manual credit card), 'CBAK' Chargeback, or 'COMP' (free)
  42
  43
  44 For Payments (cust_pay):
  45 'CARD' (credit cards), 'CHEK' (electronic check/ACH),
  46 'LECB' (phone bill billing), 'BILL' (billing), 'PREP' (prepaid card),
  47 'CASH' (cash), 'WEST' (Western Union), 'MCRD' (Manual credit card),
  48 'PPAL' (PayPal)
  49 'COMP' (free) is depricated as a payment type in cust_pay
  50
  51 =cut
  52
  53 =item payinfo
  54
  55 Payment information (payinfo) can be one of the following types:
  56
  57 Card Number, P.O., comp issuer (4-8 lowercase alphanumerics; think username)
  58 prepayment identifier (see L<FS::prepay_credit>), PayPal transaction ID
  59
  60 =cut
  61
  62 sub payinfo {
  63   my($self,$payinfo) = @_;
  64
  65   if ( defined($payinfo) ) {
  66     $self->setfield('payinfo', $payinfo);
  67     $self->paymask($self->mask_payinfo) unless $payinfo =~ /^99\d{14}$/; #token
  68   } else {
  69     $self->getfield('payinfo');
  70   }
  71 }
  72
  73 =item paycvv
  74
  75 Card Verification Value, "CVV2" (also known as CVC2 or CID), the 3 or 4 digit number on the back (or front, for American Express) of the credit card
  76
  77 =cut
  78
  79 #this prevents encrypting empty values on insert?
  80 sub paycvv {
  81   my($self,$paycvv) = @_;
  82   # This is only allowed in cust_payby (formerly cust_main)
  83   #  It shouldn't be stored longer than necessary to run the first transaction
  84   if ( defined($paycvv) ) {
  85     $self->setfield('paycvv', $paycvv);
  86   } else {
  87     $self->getfield('paycvv');
  88   }
  89 }
  90
  91 =item paymask
  92
  93 =cut
  94
  95 sub paymask {
  96   my($self, $paymask) = @_;
  97
  98   if ( defined($paymask) ) {
  99     $self->setfield('paymask', $paymask);
 100   } else {
 101     $self->getfield('paymask') || $self->mask_payinfo;
 102   }
 103 }
 104
 105 =back
 106
 107 =head1 METHODS
 108
 109 =over 4
 110
 111 =item mask_payinfo [ PAYBY, PAYINFO ]
 112
 113 This method converts the payment info (credit card, bank account, etc.) into a
 114 masked string.
 115
 116 Optionally, an arbitrary payby and payinfo can be passed.
 117
 118 =cut
 119
 120 sub mask_payinfo {
 121   my $self = shift;
 122   my $payby   = scalar(@_) ? shift : $self->payby;
 123   my $payinfo = scalar(@_) ? shift : $self->payinfo;
 124
 125   # Check to see if it's encrypted...
 126   if ( ref($self) && $self->is_encrypted($payinfo) ) {
 127     return 'N/A';
 128   } elsif ( $payinfo =~ /^99\d{14}$/ || $payinfo eq 'N/A' ) { #token
 129     return 'N/A (tokenized)'; #?
 130   } else { # if not, mask it...
 131
 132     if ($payby eq 'CARD' || $payby eq 'DCRD' || $payby eq 'MCRD') {
 133
 134       # Credit Cards
 135
 136       # special handling for Local Isracards: always show last 4
 137       if ( $payinfo =~ /^(\d{8,9})$/ ) {
 138
 139         return 'x'x(length($payinfo)-4).
 140                substr($payinfo,(length($payinfo)-4));
 141
 142       }
 143
 144       my $conf = new FS::Conf;
 145       my $mask_method = $conf->config('card_masking_method') || 'first6last4';
 146       $mask_method =~ /^first(\d+)last(\d+)$/
 147         or die "can't parse card_masking_method $mask_method";
 148       my($first, $last) = ($1, $2);
 149
 150       return substr($payinfo,0,$first).
 151              'x'x(length($payinfo)-$first-$last).
 152              substr($payinfo,(length($payinfo)-$last));
 153
 154     } elsif ($payby eq 'CHEK' || $payby eq 'DCHK' ) {
 155
 156       # Checks (Show last 2 @ bank)
 157       my( $account, $aba ) = split('@', $payinfo );
 158       return 'x'x(length($account)-2).
 159              substr($account,(length($account)-2)).
 160              ( length($aba) ? "@".$aba : '');
 161
 162     } elsif ($payby eq 'EDI') {
 163       # EDI.
 164       # These numbers have been seen anywhere from 8 to 30 digits, and
 165       # possibly more.  Lacking any better idea I'm going to mask all but
 166       # the last 4 digits.
 167       return 'x' x (length($payinfo) - 4) . substr($payinfo, -4);
 168
 169     } else { # Tie up loose ends
 170       return $payinfo;
 171     }
 172   }
 173   #die "shouldn't be reached";
 174 }
 175
 176 =item payinfo_check
 177
 178 Checks payby and payinfo.
 179
 180 For Customers (cust_main):
 181 'CARD' (credit card - automatic), 'DCRD' (credit card - on-demand),
 182 'CHEK' (electronic check - automatic), 'DCHK' (electronic check - on-demand),
 183 'LECB' (Phone bill billing), 'BILL' (billing), 'COMP' (free), or
 184 'PREPAY' (special billing type: applies a credit - see L<FS::prepay_credit> and sets billing type to I<BILL>)
 185
 186 For Refunds (cust_refund):
 187 'CARD' (credit cards), 'CHEK' (electronic check/ACH),
 188 'LECB' (Phone bill billing), 'BILL' (billing), 'CASH' (cash),
 189 'WEST' (Western Union), 'MCRD' (Manual credit card), 'CBAK' (Chargeback),  or 'COMP' (free)
 190
 191 For Payments (cust_pay):
 192 'CARD' (credit cards), 'CHEK' (electronic check/ACH),
 193 'LECB' (phone bill billing), 'BILL' (billing), 'PREP' (prepaid card),
 194 'CASH' (cash), 'WEST' (Western Union), or 'MCRD' (Manual credit card)
 195 'COMP' (free) is depricated as a payment type in cust_pay
 196
 197 =cut
 198
 199 sub payinfo_check {
 200   my $self = shift;
 201
 202   FS::payby->can_payby($self->table, $self->payby)
 203     or return "Illegal payby: ". $self->payby;
 204
 205   if ( $self->payby eq 'CARD' && ! $self->is_encrypted($self->payinfo) ) {
 206     my $payinfo = $self->payinfo;
 207     if ( $ignore_masked_payinfo and $self->mask_payinfo eq $self->payinfo ) {
 208       # allow it
 209     } else {
 210       $payinfo =~ s/\D//g;
 211       $self->payinfo($payinfo);
 212       if ( $self->payinfo ) {
 213         $self->payinfo =~ /^(\d{13,16}|\d{8,9})$/
 214           or return "Illegal (mistyped?) credit card number (payinfo)";
 215         $self->payinfo($1);
 216         validate($self->payinfo) or return "Illegal credit card number";
 217         return "Unknown card type" if $self->payinfo !~ /^99\d{14}$/ #token
 218                                    && cardtype($self->payinfo) eq "Unknown";
 219       } else {
 220         $self->payinfo('N/A'); #???
 221       }
 222     }
 223   } else {
 224     if ( $self->is_encrypted($self->payinfo) ) {
 225       #something better?  all it would cause is a decryption error anyway?
 226       my $error = $self->ut_anything('payinfo');
 227       return $error if $error;
 228     } else {
 229       my $error = $self->ut_textn('payinfo');
 230       return $error if $error;
 231     }
 232   }
 233
 234 }
 235
 236 =item payby_payinfo_pretty [ LOCALE ]
 237
 238 Returns payment method and information (suitably masked, if applicable) as
 239 a human-readable string, such as:
 240
 241   Card #54xxxxxxxxxxxx32
 242
 243 or
 244
 245   Check #119006
 246
 247 =cut
 248
 249 sub payby_payinfo_pretty {
 250   my $self = shift;
 251   my $locale = shift;
 252   my $lh = FS::L10N->get_handle($locale);
 253   if ( $self->payby eq 'CARD' ) {
 254     $lh->maketext('Card #') . $self->paymask;
 255   } elsif ( $self->payby eq 'CHEK' ) {
 256
 257     #false laziness w/view/cust_main/payment_history.html::translate_payinfo
 258     my( $account, $aba ) = split('@', $self->paymask );
 259
 260     if ( $aba =~ /^(\d{5})\.(\d{3})$/ ) { #blame canada
 261       my($branch, $routing) = ($1, $2);
 262       $lh->maketext("Routing [_1], Branch [_2], Acct [_3]",
 263                      $routing, $branch, $account);
 264     } else {
 265       $lh->maketext("Routing [_1], Acct [_2]", $aba, $account);
 266     }
 267
 268   } elsif ( $self->payby eq 'BILL' ) {
 269     $lh->maketext('Check #') . $self->payinfo;
 270   } elsif ( $self->payby eq 'PREP' ) {
 271     $lh->maketext('Prepaid card #') . $self->payinfo;
 272   } elsif ( $self->payby eq 'CASH' ) {
 273     $lh->maketext('Cash') . ' ' . $self->payinfo;
 274   } elsif ( $self->payby eq 'WEST' ) {
 275     # does Western Union localize their name?
 276     $lh->maketext('Western Union');
 277   } elsif ( $self->payby eq 'MCRD' ) {
 278     $lh->maketext('Manual credit card');
 279   } elsif ( $self->payby eq 'EDI' ) {
 280     $lh->maketext('EDI') . ' ' . $self->paymask;
 281   } elsif ( $self->payby eq 'PPAL' ) {
 282     $lh->maketext('PayPal transaction#') . $self->order_number;
 283   } else {
 284     $self->payby. ' '. $self->payinfo;
 285   }
 286 }
 287
 288 =item payinfo_used [ PAYINFO ]
 289
 290 Returns 1 if there's an existing payment using this payinfo.  This can be
 291 used to set the 'recurring payment' flag required by some processors.
 292
 293 =cut
 294
 295 sub payinfo_used {
 296   my $self = shift;
 297   my $payinfo = shift || $self->payinfo;
 298   my %hash = (
 299     'custnum' => $self->custnum,
 300     'payby'   => 'CARD',
 301   );
 302
 303   return 1
 304   if qsearch('cust_pay', { %hash, 'payinfo' => $payinfo } )
 305   || qsearch('cust_pay',
 306     { %hash, 'paymask' => $self->mask_payinfo('CARD', $payinfo) }  )
 307   ;
 308
 309   return 0;
 310 }
 311
 312 =item display_status
 313
 314 For transactions that have both 'status' and 'failure_status', shows the
 315 status in a single, display-friendly string.
 316
 317 =cut
 318
 319 sub display_status {
 320   my $self = shift;
 321   my %status = (
 322     'done'        => 'Approved',
 323     'expired'     => 'Card Expired',
 324     'stolen'      => 'Lost/Stolen',
 325     'pickup'      => 'Pick Up Card',
 326     'nsf'         => 'Insufficient Funds',
 327     'inactive'    => 'Inactive Account',
 328     'blacklisted' => 'Blacklisted',
 329     'declined'    => 'Declined',
 330     'approved'    => 'Approved',
 331   );
 332   if ( $self->failure_status ) {
 333     return $status{$self->failure_status};
 334   } else {
 335     return $status{$self->status};
 336   }
 337 }
 338
 339 =back
 340
 341 =head1 BUGS
 342
 343 =head1 SEE ALSO
 344
 345 L<FS::payby>, L<FS::Record>
 346
 347 =cut
 348
 349 1;
 350