RT# 79737 - Added ability to us a cc surcharge of a flat fee.
[freeside.git] / FS / FS / cust_main / Billing_Realtime.pm
1 package FS::cust_main::Billing_Realtime;
2
3 use strict;
4 use vars qw( $conf $DEBUG $me );
5 use vars qw( $realtime_bop_decline_quiet ); #ugh
6 use Carp;
7 use Data::Dumper;
8 use Business::CreditCard 0.35;
9 use Business::OnlinePayment;
10 use FS::UID qw( dbh myconnect );
11 use FS::Record qw( qsearch qsearchs );
12 use FS::payby;
13 use FS::cust_pay;
14 use FS::cust_pay_pending;
15 use FS::cust_bill_pay;
16 use FS::cust_refund;
17 use FS::banned_pay;
18 use FS::payment_gateway;
19
20 $realtime_bop_decline_quiet = 0;
21
22 # 1 is mostly method/subroutine entry and options
23 # 2 traces progress of some operations
24 # 3 is even more information including possibly sensitive data
25 $DEBUG = 0;
26 $me = '[FS::cust_main::Billing_Realtime]';
27
28 our $BOP_TESTING = 0;
29 our $BOP_TESTING_SUCCESS = 1;
30
31 install_callback FS::UID sub { 
32   $conf = new FS::Conf;
33   #yes, need it for stuff below (prolly should be cached)
34 };
35
36 =head1 NAME
37
38 FS::cust_main::Billing_Realtime - Realtime billing mixin for cust_main
39
40 =head1 SYNOPSIS
41
42 =head1 DESCRIPTION
43
44 These methods are available on FS::cust_main objects.
45
46 =head1 METHODS
47
48 =over 4
49
50 =item realtime_cust_payby
51
52 =cut
53
54 sub realtime_cust_payby {
55   my( $self, %options ) = @_;
56
57   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
58
59   $options{amount} = $self->balance unless exists( $options{amount} );
60
61   my @cust_payby = $self->cust_payby('CARD','CHEK');
62                                                    
63   my $error;
64   foreach my $cust_payby (@cust_payby) {
65     $error = $cust_payby->realtime_bop( %options, );
66     last unless $error;
67   }
68
69   #XXX what about the earlier errors?
70
71   $error;
72
73 }
74
75 =item realtime_collect [ OPTION => VALUE ... ]
76
77 Attempt to collect the customer's current balance with a realtime credit 
78 card or electronic check transaction (see realtime_bop() below).
79
80 Returns the result of realtime_bop(): nothing, an error message, or a 
81 hashref of state information for a third-party transaction.
82
83 Available options are: I<method>, I<amount>, I<description>, I<invnum>, I<quiet>, I<paynum_ref>, I<payunique>, I<session_id>, I<pkgnum>
84
85 I<method> is one of: I<CC> or I<ECHECK>.  If none is specified
86 then it is deduced from the customer record.
87
88 If no I<amount> is specified, then the customer balance is used.
89
90 The additional options I<payname>, I<address1>, I<address2>, I<city>, I<state>,
91 I<zip>, I<payinfo> and I<paydate> are also available.  Any of these options,
92 if set, will override the value from the customer record.
93
94 I<description> is a free-text field passed to the gateway.  It defaults to
95 the value defined by the business-onlinepayment-description configuration
96 option, or "Internet services" if that is unset.
97
98 If an I<invnum> is specified, this payment (if successful) is applied to the
99 specified invoice.
100
101 I<apply> will automatically apply a resulting payment.
102
103 I<quiet> can be set true to suppress email decline notices.
104
105 I<paynum_ref> can be set to a scalar reference.  It will be filled in with the
106 resulting paynum, if any.
107
108 I<payunique> is a unique identifier for this payment.
109
110 I<session_id> is a session identifier associated with this payment.
111
112 I<depend_jobnum> allows payment capture to unlock export jobs
113
114 =cut
115
116 # Currently only used by ClientAPI
117 sub realtime_collect {
118   my( $self, %options ) = @_;
119
120   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
121
122   if ( $DEBUG ) {
123     warn "$me realtime_collect:\n";
124     warn "  $_ => $options{$_}\n" foreach keys %options;
125   }
126
127   $options{amount} = $self->balance unless exists( $options{amount} );
128   return '' unless $options{amount} > 0;
129
130   #huh, in v4, realtime_bop no longer will just process a card without passing
131   # payinfo or cust_payby...
132   if ( ! $options{'payinfo'} && ! $options{'cust_payby'} && $self->has_cust_payby_auto ) {
133     my @cust_payby = $self->cust_payby;
134     $options{'cust_payby'} = $cust_payby[0];
135   }
136
137   return $self->realtime_bop({%options});
138
139 }
140
141 =item realtime_bop { [ ARG => VALUE ... ] }
142
143 Runs a realtime credit card or ACH (electronic check) transaction
144 via a Business::OnlinePayment realtime gateway.  See
145 L<http://420.am/business-onlinepayment> for supported gateways.
146
147 Required arguments in the hashref are I<amount> and either
148 I<cust_payby> or I<method>, I<payinfo> and (as applicable for method)
149 I<payname>, I<address1>, I<address2>, I<city>, I<state>, I<zip> and I<paydate>.
150
151 Available methods are: I<CC>, I<ECHECK>, or I<PAYPAL>
152
153 Available optional arguments are: I<description>, I<invnum>, I<apply>, I<quiet>, I<paynum_ref>, I<payunique>, I<session_id>
154
155 I<description> is a free-text field passed to the gateway.  It defaults to
156 the value defined by the business-onlinepayment-description configuration
157 option, or "Internet services" if that is unset.
158
159 If an I<invnum> is specified, this payment (if successful) is applied to the
160 specified invoice.  If the customer has exactly one open invoice, that 
161 invoice number will be assumed.  If you don't specify an I<invnum> you might 
162 want to call the B<apply_payments> method or set the I<apply> option.
163
164 I<no_invnum> can be set to true to prevent that default invnum from being set.
165
166 I<apply> can be set to true to run B<apply_payments_and_credits> on success.
167
168 I<no_auto_apply> can be set to true to set that flag on the resulting payment
169 (prevents payment from being applied by B<apply_payments> or B<apply_payments_and_credits>,
170 but will still be applied if I<invnum> exists...use with I<no_invnum> for intended effect.)
171
172 I<quiet> can be set true to surpress email decline notices.
173
174 I<paynum_ref> can be set to a scalar reference.  It will be filled in with the
175 resulting paynum, if any.
176
177 I<payunique> is a unique identifier for this payment.
178
179 I<session_id> is a session identifier associated with this payment.
180
181 I<depend_jobnum> allows payment capture to unlock export jobs
182
183 I<discount_term> attempts to take a discount by prepaying for discount_term.
184 The payment will fail if I<amount> is incorrect for this discount term.
185
186 A direct (Business::OnlinePayment) transaction will return nothing on success,
187 or an error message on failure.
188
189 A third-party transaction will return a hashref containing:
190
191 - popup_url: the URL to which a browser should be redirected to complete 
192   the transaction.
193 - collectitems: an arrayref of name-value pairs to be posted to popup_url.
194 - reference: a reference ID for the transaction, to show the customer.
195
196 (moved from cust_bill) (probably should get realtime_{card,ach,lec} here too)
197
198 =cut
199
200 # some helper routines
201 #
202 # _bop_recurring_billing: Checks whether this payment should have the 
203 # recurring_billing flag used by some B:OP interfaces (IPPay, PlugnPay,
204 # vSecure, etc.). This works in two different modes:
205 # - actual_oncard (default): treat the payment as recurring if the customer
206 #   has made a payment using this card before.
207 # - transaction_is_recur: treat the payment as recurring if the invoice
208 #   being paid has any recurring package charges.
209
210 sub _bop_recurring_billing {
211   my( $self, %opt ) = @_;
212
213   my $method = scalar($conf->config('credit_card-recurring_billing_flag'));
214
215   if ( defined($method) && $method eq 'transaction_is_recur' ) {
216
217     return 1 if $opt{'trans_is_recur'};
218
219   } else {
220
221     # return 1 if the payinfo has been used for another payment
222     return $self->payinfo_used($opt{'payinfo'}); # in payinfo_Mixin
223
224   }
225
226   return 0;
227
228 }
229
230 #can run safely as class method if opt payment_gateway already exists
231 sub _payment_gateway {
232   my ($self, $options) = @_;
233
234   if ( $options->{'fake_gatewaynum'} ) {
235         $options->{payment_gateway} =
236             qsearchs('payment_gateway',
237                       { 'gatewaynum' => $options->{'fake_gatewaynum'}, }
238                     );
239   }
240
241   $options->{payment_gateway} = $self->agent->payment_gateway( %$options )
242     unless exists($options->{payment_gateway});
243
244   $options->{payment_gateway};
245 }
246
247 # not a method!!!
248 sub _bop_auth {
249   my ($options) = @_;
250
251   (
252     'login'    => $options->{payment_gateway}->gateway_username,
253     'password' => $options->{payment_gateway}->gateway_password,
254   );
255 }
256
257 ### not a method!
258 sub _bop_options {
259   my ($options) = @_;
260
261   $options->{payment_gateway}->gatewaynum
262     ? $options->{payment_gateway}->options
263     : @{ $options->{payment_gateway}->get('options') };
264
265 }
266
267 sub _bop_defaults {
268   my ($self, $options) = @_;
269
270   unless ( $options->{'description'} ) {
271     if ( $conf->exists('business-onlinepayment-description') ) {
272       my $dtempl = $conf->config('business-onlinepayment-description');
273
274       my $agent = $self->agent->agent;
275       #$pkgs... not here
276       $options->{'description'} = eval qq("$dtempl");
277     } else {
278       $options->{'description'} = 'Internet services';
279     }
280   }
281
282   # Default invoice number if the customer has exactly one open invoice.
283   unless ( $options->{'invnum'} || $options->{'no_invnum'} ) {
284     $options->{'invnum'} = '';
285     my @open = $self->open_cust_bill;
286     $options->{'invnum'} = $open[0]->invnum if scalar(@open) == 1;
287   }
288
289 }
290
291 # not a method!
292 sub _bop_cust_payby_options {
293   my ($options) = @_;
294   my $cust_payby = $options->{'cust_payby'};
295   if ($cust_payby) {
296
297     $options->{'method'} = FS::payby->payby2bop( $cust_payby->payby );
298
299     if ($cust_payby->payby =~ /^(CARD|DCRD)$/) {
300       # false laziness with cust_payby->check
301       #   which might not have been run yet
302       my( $m, $y );
303       if ( $cust_payby->paydate =~ /^(\d{1,2})[\/\-](\d{2}(\d{2})?)$/ ) {
304         ( $m, $y ) = ( $1, length($2) == 4 ? $2 : "20$2" );
305       } elsif ( $cust_payby->paydate =~ /^19(\d{2})[\/\-](\d{1,2})[\/\-]\d+$/ ) {
306         ( $m, $y ) = ( $2, "19$1" );
307       } elsif ( $cust_payby->paydate =~ /^(20)?(\d{2})[\/\-](\d{1,2})[\/\-]\d+$/ ) {
308         ( $m, $y ) = ( $3, "20$2" );
309       } else {
310         return "Illegal expiration date: ". $cust_payby->paydate;
311       }
312       $m = sprintf('%02d',$m);
313       $options->{paydate} = "$y-$m-01";
314     } else {
315       $options->{paydate} = '';
316     }
317
318     $options->{$_} = $cust_payby->$_() 
319       for qw( payinfo paycvv paymask paystart_month paystart_year 
320               payissue payname paystate paytype payip );
321
322     if ( $cust_payby->locationnum ) {
323       my $cust_location = $cust_payby->cust_location;
324       $options->{$_} = $cust_location->$_() for qw( address1 address2 city state zip );
325     }
326   }
327 }
328
329 # can be called as class method,
330 # but can't load default name/phone fields as class method
331 sub _bop_content {
332   my ($self, $options) = @_;
333   my %content = ();
334
335   my $payip = $options->{'payip'};
336   $content{customer_ip} = $payip if length($payip);
337
338   $content{invoice_number} = $options->{'invnum'}
339     if exists($options->{'invnum'}) && length($options->{'invnum'});
340
341   $content{email_customer} = 
342     (    $conf->exists('business-onlinepayment-email_customer')
343       || $conf->exists('business-onlinepayment-email-override') );
344       
345   my ($payname, $payfirst, $paylast);
346   if ( $options->{payname} && $options->{method} ne 'ECHECK' ) {
347     ($payname = $options->{payname}) =~
348       /^\s*([\w \,\.\-\']*)?\s+([\w\,\.\-\']+)\s*$/
349       or return "Illegal payname $payname";
350     ($payfirst, $paylast) = ($1, $2);
351   } elsif (ref($self)) { # can't set payname if called as class method
352     $payfirst = $self->getfield('first');
353     $paylast = $self->getfield('last');
354     $payname = "$payfirst $paylast";
355   }
356
357   $content{last_name} = $paylast if $paylast;
358   $content{first_name} = $payfirst if $payfirst;
359
360   $content{name} = $payname if $payname;
361
362   $content{address} = $options->{'address1'};
363   my $address2 = $options->{'address2'};
364   $content{address} .= ", ". $address2 if length($address2);
365
366   $content{city} = $options->{'city'};
367   $content{state} = $options->{'state'};
368   $content{zip} = $options->{'zip'};
369   $content{country} = $options->{'country'};
370
371   # can't set phone if called as class method
372   $content{phone} = $self->daytime || $self->night
373     if ref($self);
374
375   my $currency =    $conf->exists('business-onlinepayment-currency')
376                  && $conf->config('business-onlinepayment-currency');
377   $content{currency} = $currency if $currency;
378
379   \%content;
380 }
381
382 # updates payinfo and cust_payby options with token from transaction
383 # can be called as a class method
384 sub _tokenize_card {
385   my ($self,$transaction,$options) = @_;
386   if ( $transaction->can('card_token') 
387        and $transaction->card_token 
388        and !$self->tokenized($options->{'payinfo'})
389   ) {
390     $options->{'payinfo'} = $transaction->card_token;
391     $options->{'cust_payby'}->payinfo($transaction->card_token) if $options->{'cust_payby'};
392     return $transaction->card_token;
393   }
394   return '';
395 }
396
397 my %bop_method2payby = (
398   'CC'     => 'CARD',
399   'ECHECK' => 'CHEK',
400   'PAYPAL' => 'PPAL',
401 );
402
403 sub realtime_bop {
404   my $self = shift;
405
406   confess "Can't call realtime_bop within another transaction ".
407           '($FS::UID::AutoCommit is false)'
408     unless $FS::UID::AutoCommit;
409
410   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
411
412   my $log = FS::Log->new('FS::cust_main::Billing_Realtime::realtime_bop');
413  
414   my %options = ();
415   if (ref($_[0]) eq 'HASH') {
416     %options = %{$_[0]};
417   } else {
418     my ( $method, $amount ) = ( shift, shift );
419     %options = @_;
420     $options{method} = $method;
421     $options{amount} = $amount;
422   }
423
424   return '' unless $options{amount} > 0;
425
426   # set fields from passed cust_payby
427   _bop_cust_payby_options(\%options);
428
429   # check for banned credit card/ACH
430   my $ban = FS::banned_pay->ban_search(
431     'payby'   => $bop_method2payby{$options{method}},
432     'payinfo' => $options{payinfo},
433   );
434   return "Banned credit card" if $ban && $ban->bantype ne 'warn';
435
436   # possibly run a separate transaction to tokenize card number,
437   #   so that we never store tokenized card info in cust_pay_pending
438   if (($options{method} eq 'CC') && !$self->tokenized($options{'payinfo'})) {
439     my $token_error = $self->realtime_tokenize(\%options);
440     return $token_error if $token_error;
441     # in theory, all cust_payby will be tokenized during original save,
442     # so we shouldn't get here with opt cust_payby...but just in case...
443     if ($options{'cust_payby'} && $self->tokenized($options{'payinfo'})) {
444       $token_error = $options{'cust_payby'}->replace;
445       return $token_error if $token_error;
446     }
447   }
448
449   ### 
450   # optional credit card surcharge
451   ###
452
453   my $cc_surcharge = 0;
454   my $cc_surcharge_pct = 0;
455   $cc_surcharge_pct = $conf->config('credit-card-surcharge-percentage', $self->agentnum) 
456     if $conf->config('credit-card-surcharge-percentage', $self->agentnum)
457     && $options{method} eq 'CC';
458
459   my $cc_surcharge_flat = 0;
460   $cc_surcharge_flat = $conf->config('credit-card-surcharge-flatfee', $self->agentnum)
461     if $conf->config('credit-card-surcharge-flatfee', $self->agentnum)
462     && $options{method} eq 'CC';
463
464   # always add cc surcharge if called from event 
465   if($options{'cc_surcharge_from_event'} && ($cc_surcharge_pct > 0 || $cc_surcharge_flat > 0)) {
466     if ($options{'amount'} > 0) {
467       $cc_surcharge = ($options{'amount'} * ($cc_surcharge_pct / 100)) + $cc_surcharge_flat;
468       $options{'amount'} += $cc_surcharge;
469       $options{'amount'} = sprintf("%.2f", $options{'amount'}); # round (again)?
470     }
471   }
472   elsif($cc_surcharge_pct > 0 || $cc_surcharge_flat > 0) {
473     # we're called not from event (i.e. from a
474     # payment screen), so consider the given
475                 # amount as post-surcharge
476     $cc_surcharge = $options{'amount'} - (($options{'amount'} - $cc_surcharge_flat) / ( 1 + $cc_surcharge_pct/100 )) if $options{'amount'} > 0;
477   }
478   
479   $cc_surcharge = sprintf("%.2f",$cc_surcharge) if $cc_surcharge > 0;
480   $options{'cc_surcharge'} = $cc_surcharge;
481
482
483   if ( $DEBUG ) {
484     warn "$me realtime_bop (new): $options{method} $options{amount}\n";
485     warn " cc_surcharge = $cc_surcharge\n";
486   }
487   if ( $DEBUG > 2 ) {
488     warn "  $_ => $options{$_}\n" foreach keys %options;
489   }
490
491   return $self->fake_bop(\%options) if $options{'fake'};
492
493   $self->_bop_defaults(\%options);
494
495   return "Missing payinfo"
496     unless $options{'payinfo'};
497
498   ###
499   # set trans_is_recur based on invnum if there is one
500   ###
501
502   my $trans_is_recur = 0;
503   if ( $options{'invnum'} ) {
504
505     my $cust_bill = qsearchs('cust_bill', { 'invnum' => $options{'invnum'} } );
506     die "invnum ". $options{'invnum'}. " not found" unless $cust_bill;
507
508     my @part_pkg =
509       map  { $_->part_pkg }
510       grep { $_ }
511       map  { $_->cust_pkg }
512       $cust_bill->cust_bill_pkg;
513
514     $trans_is_recur = 1
515       if grep { $_->freq ne '0' } @part_pkg;
516
517   }
518
519   ###
520   # select a gateway
521   ###
522
523   my $payment_gateway =  $self->_payment_gateway( \%options );
524   my $namespace = $payment_gateway->gateway_namespace;
525
526   eval "use $namespace";  
527   die $@ if $@;
528
529   ###
530   # check for term discount validity
531   ###
532
533   my $discount_term = $options{discount_term};
534   if ( $discount_term ) {
535     my $bill = ($self->cust_bill)[-1]
536       or return "Can't apply a term discount to an unbilled customer";
537     my $plan = FS::discount_plan->new(
538       cust_bill => $bill,
539       months    => $discount_term
540     ) or return "No discount available for term '$discount_term'";
541     
542     if ( $plan->discounted_total != $options{amount} ) {
543       return "Incorrect term prepayment amount (term $discount_term, amount $options{amount}, requires ".$plan->discounted_total.")";
544     }
545   }
546
547   ###
548   # massage data
549   ###
550
551   my $bop_content = $self->_bop_content(\%options);
552   return $bop_content unless ref($bop_content);
553
554   my @invoicing_list = $self->invoicing_list_emailonly;
555   if ( $conf->exists('emailinvoiceautoalways')
556        || $conf->exists('emailinvoiceauto') && ! @invoicing_list
557        || ( $conf->exists('emailinvoiceonly') && ! @invoicing_list ) ) {
558     push @invoicing_list, $self->all_emails;
559   }
560
561   my $email = ($conf->exists('business-onlinepayment-email-override'))
562               ? $conf->config('business-onlinepayment-email-override')
563               : $invoicing_list[0];
564
565   my $paydate = '';
566   my %content = ();
567
568   if ( $namespace eq 'Business::OnlinePayment' ) {
569
570     if ( $options{method} eq 'CC' ) {
571
572       $content{card_number} = $options{payinfo};
573       $paydate = $options{'paydate'};
574       $paydate =~ /^\d{2}(\d{2})[\/\-](\d+)[\/\-]\d+$/;
575       $content{expiration} = "$2/$1";
576
577       $content{cvv2} = $options{'paycvv'}
578         if length($options{'paycvv'});
579
580       my $paystart_month = $options{'paystart_month'};
581       my $paystart_year  = $options{'paystart_year'};
582       $content{card_start} = "$paystart_month/$paystart_year"
583         if $paystart_month && $paystart_year;
584
585       my $payissue       = $options{'payissue'};
586       $content{issue_number} = $payissue if $payissue;
587
588       if ( $self->_bop_recurring_billing(
589              'payinfo'        => $options{'payinfo'},
590              'trans_is_recur' => $trans_is_recur,
591            )
592          )
593       {
594         $content{recurring_billing} = 'YES';
595         $content{acct_code} = 'rebill'
596           if $conf->exists('credit_card-recurring_billing_acct_code');
597       }
598
599     } elsif ( $options{method} eq 'ECHECK' ){
600
601       ( $content{account_number}, $content{routing_code} ) =
602         split('@', $options{payinfo});
603       $content{bank_name} = $options{payname};
604       $content{bank_state} = $options{'paystate'};
605       $content{account_type}= uc($options{'paytype'}) || 'PERSONAL CHECKING';
606
607       $content{company} = $self->company if $self->company;
608
609       if ( $content{account_type} =~ /BUSINESS/i && $self->company ) {
610         $content{account_name} = $self->company;
611       } else {
612         $content{account_name} = $self->getfield('first'). ' '.
613                                  $self->getfield('last');
614       }
615
616       $content{customer_org} = $self->company ? 'B' : 'I';
617       $content{state_id}       = exists($options{'stateid'})
618                                    ? $options{'stateid'}
619                                    : $self->getfield('stateid');
620       $content{state_id_state} = exists($options{'stateid_state'})
621                                    ? $options{'stateid_state'}
622                                    : $self->getfield('stateid_state');
623       $content{customer_ssn} = exists($options{'ss'})
624                                  ? $options{'ss'}
625                                  : $self->ss;
626
627     } else {
628       die "unknown method ". $options{method};
629     }
630
631   } elsif ( $namespace eq 'Business::OnlineThirdPartyPayment' ) {
632     #move along
633   } else {
634     die "unknown namespace $namespace";
635   }
636
637   ###
638   # run transaction(s)
639   ###
640
641   my $balance = exists( $options{'balance'} )
642                   ? $options{'balance'}
643                   : $self->balance;
644
645   warn "claiming mutex on customer ". $self->custnum. "\n" if $DEBUG > 1;
646   $self->select_for_update; #mutex ... just until we get our pending record in
647   warn "obtained mutex on customer ". $self->custnum. "\n" if $DEBUG > 1;
648
649   #the checks here are intended to catch concurrent payments
650   #double-form-submission prevention is taken care of in cust_pay_pending::check
651
652   #check the balance
653   return "The customer's balance has changed; $options{method} transaction aborted."
654     if $self->balance < $balance;
655
656   #also check and make sure there aren't *other* pending payments for this cust
657
658   my @pending = qsearch('cust_pay_pending', {
659     'custnum' => $self->custnum,
660     'status'  => { op=>'!=', value=>'done' } 
661   });
662
663   #for third-party payments only, remove pending payments if they're in the 
664   #'thirdparty' (waiting for customer action) state.
665   if ( $namespace eq 'Business::OnlineThirdPartyPayment' ) {
666     foreach ( grep { $_->status eq 'thirdparty' } @pending ) {
667       my $error = $_->delete;
668       warn "error deleting unfinished third-party payment ".
669           $_->paypendingnum . ": $error\n"
670         if $error;
671     }
672     @pending = grep { $_->status ne 'thirdparty' } @pending;
673   }
674
675   return "A payment is already being processed for this customer (".
676          join(', ', map 'paypendingnum '. $_->paypendingnum, @pending ).
677          "); $options{method} transaction aborted."
678     if scalar(@pending);
679
680   #okay, good to go, if we're a duplicate, cust_pay_pending will kick us out
681
682   my $cust_pay_pending = new FS::cust_pay_pending {
683     'custnum'           => $self->custnum,
684     'paid'              => $options{amount},
685     '_date'             => '',
686     'payby'             => $bop_method2payby{$options{method}},
687     'payinfo'           => $options{payinfo},
688     'paymask'           => $options{paymask},
689     'paydate'           => $paydate,
690     'recurring_billing' => $content{recurring_billing},
691     'pkgnum'            => $options{'pkgnum'},
692     'status'            => 'new',
693     'gatewaynum'        => $payment_gateway->gatewaynum || '',
694     'session_id'        => $options{session_id} || '',
695     'jobnum'            => $options{depend_jobnum} || '',
696   };
697   $cust_pay_pending->payunique( $options{payunique} )
698     if defined($options{payunique}) && length($options{payunique});
699
700   warn "inserting cust_pay_pending record for customer ". $self->custnum. "\n"
701     if $DEBUG > 1;
702   my $cpp_new_err = $cust_pay_pending->insert; #mutex lost when this is inserted
703   return $cpp_new_err if $cpp_new_err;
704
705   warn "inserted cust_pay_pending record for customer ". $self->custnum. "\n"
706     if $DEBUG > 1;
707   warn Dumper($cust_pay_pending) if $DEBUG > 2;
708
709   my( $action1, $action2 ) =
710     split( /\s*\,\s*/, $payment_gateway->gateway_action );
711
712   my $transaction = new $namespace( $payment_gateway->gateway_module,
713                                     _bop_options(\%options),
714                                   );
715
716   $transaction->content(
717     'type'           => $options{method},
718     _bop_auth(\%options),          
719     'action'         => $action1,
720     'description'    => $options{'description'},
721     'amount'         => $options{amount},
722     #'invoice_number' => $options{'invnum'},
723     'customer_id'    => $self->custnum,
724     %$bop_content,
725     'reference'      => $cust_pay_pending->paypendingnum, #for now
726     'callback_url'   => $payment_gateway->gateway_callback_url,
727     'cancel_url'     => $payment_gateway->gateway_cancel_url,
728     'email'          => $email,
729     %content, #after
730   );
731
732   $cust_pay_pending->status('pending');
733   my $cpp_pending_err = $cust_pay_pending->replace;
734   return $cpp_pending_err if $cpp_pending_err;
735
736   warn Dumper($transaction) if $DEBUG > 2;
737
738   unless ( $BOP_TESTING ) {
739     $transaction->test_transaction(1)
740       if $conf->exists('business-onlinepayment-test_transaction');
741     $transaction->submit();
742   } else {
743     if ( $BOP_TESTING_SUCCESS ) {
744       $transaction->is_success(1);
745       $transaction->authorization('fake auth');
746     } else {
747       $transaction->is_success(0);
748       $transaction->error_message('fake failure');
749     }
750   }
751
752   if ( $transaction->is_success() && $namespace eq 'Business::OnlineThirdPartyPayment' ) {
753
754     $cust_pay_pending->status('thirdparty');
755     my $cpp_err = $cust_pay_pending->replace;
756     return { error => $cpp_err } if $cpp_err;
757     return { reference => $cust_pay_pending->paypendingnum,
758              map { $_ => $transaction->$_ } qw ( popup_url collectitems ) };
759
760   } elsif ( $transaction->is_success() && $action2 ) {
761
762     $cust_pay_pending->status('authorized');
763     my $cpp_authorized_err = $cust_pay_pending->replace;
764     return $cpp_authorized_err if $cpp_authorized_err;
765
766     my $auth = $transaction->authorization;
767     my $ordernum = $transaction->can('order_number')
768                    ? $transaction->order_number
769                    : '';
770
771     my $capture =
772       new Business::OnlinePayment( $payment_gateway->gateway_module,
773                                    _bop_options(\%options),
774                                  );
775
776     my %capture = (
777       %content,
778       type           => $options{method},
779       action         => $action2,
780       _bop_auth(\%options),          
781       order_number   => $ordernum,
782       amount         => $options{amount},
783       authorization  => $auth,
784       description    => $options{'description'},
785     );
786
787     foreach my $field (qw( authorization_source_code returned_ACI
788                            transaction_identifier validation_code           
789                            transaction_sequence_num local_transaction_date    
790                            local_transaction_time AVS_result_code          )) {
791       $capture{$field} = $transaction->$field() if $transaction->can($field);
792     }
793
794     $capture->content( %capture );
795
796     $capture->test_transaction(1)
797       if $conf->exists('business-onlinepayment-test_transaction');
798     $capture->submit();
799
800     unless ( $capture->is_success ) {
801       my $e = "Authorization successful but capture failed, custnum #".
802               $self->custnum. ': '.  $capture->result_code.
803               ": ". $capture->error_message;
804       warn $e;
805       return $e;
806     }
807
808   }
809
810   ###
811   # remove paycvv after initial transaction
812   ###
813
814   # compare to FS::cust_main::save_cust_payby - check both to make sure working correctly
815   if ( length($options{'paycvv'})
816        && ! grep { $_ eq cardtype($options{payinfo}) } $conf->config('cvv-save')
817   ) {
818     my $error = $self->remove_cvv_from_cust_payby($options{payinfo});
819     if ( $error ) {
820       $log->critical('Error removing cvv for cust '.$self->custnum.': '.$error);
821       #not returning error, should at least attempt to handle results of an otherwise valid transaction
822       warn "WARNING: error removing cvv: $error\n";
823     }
824   }
825
826   ###
827   # Tokenize
828   ###
829
830   # This block will only run if the B::OP module supports card_token but not the Tokenize transaction;
831   #   if that never happens, we should get rid of it (as it has the potential to store real card numbers on error)
832   if (my $card_token = $self->_tokenize_card($transaction,\%options)) {
833     # cpp will be replaced in _realtime_bop_result
834     $cust_pay_pending->payinfo($card_token);
835     if ($options{'cust_payby'} and my $error = $options{'cust_payby'}->replace) {
836       $log->critical('Error storing token for cust '.$self->custnum.', cust_payby '.$options{'cust_payby'}->custpaybynum.': '.$error);
837       #not returning error, should at least attempt to handle results of an otherwise valid transaction
838       #this leaves real card number in cust_payby, but can't do much else if cust_payby won't replace
839     }
840   }
841
842   ###
843   # result handling
844   ###
845
846   $self->_realtime_bop_result( $cust_pay_pending, $transaction, %options );
847
848 }
849
850 =item fake_bop
851
852 =cut
853
854 sub fake_bop {
855   my $self = shift;
856
857   my %options = ();
858   if (ref($_[0]) eq 'HASH') {
859     %options = %{$_[0]};
860   } else {
861     my ( $method, $amount ) = ( shift, shift );
862     %options = @_;
863     $options{method} = $method;
864     $options{amount} = $amount;
865   }
866   
867   if ( $options{'fake_failure'} ) {
868      return "Error: No error; test failure requested with fake_failure";
869   }
870
871   my $cust_pay = new FS::cust_pay ( {
872      'custnum'  => $self->custnum,
873      'invnum'   => $options{'invnum'},
874      'paid'     => $options{amount},
875      '_date'    => '',
876      'payby'    => $bop_method2payby{$options{method}},
877      'payinfo'  => '4111111111111111',
878      'paydate'  => '2012-05-01',
879      'processor'      => 'FakeProcessor',
880      'auth'           => '54',
881      'order_number'   => '32',
882   } );
883   $cust_pay->payunique( $options{payunique} ) if length($options{payunique});
884
885   if ( $DEBUG ) {
886       warn "fake_bop\n cust_pay: ". Dumper($cust_pay) . "\n options: ";
887       warn "  $_ => $options{$_}\n" foreach keys %options;
888   }
889
890   my $error = $cust_pay->insert($options{'manual'} ? ( 'manual' => 1 ) : () );
891
892   if ( $error ) {
893     $cust_pay->invnum(''); #try again with no specific invnum
894     my $error2 = $cust_pay->insert( $options{'manual'} ?
895                                     ( 'manual' => 1 ) : ()
896                                   );
897     if ( $error2 ) {
898       # gah, even with transactions.
899       my $e = 'WARNING: Card/ACH debited but database not updated - '.
900               "error inserting (fake!) payment: $error2".
901               " (previously tried insert with invnum #$options{'invnum'}" .
902               ": $error )";
903       warn $e;
904       return $e;
905     }
906   }
907
908   if ( $options{'paynum_ref'} ) {
909     ${ $options{'paynum_ref'} } = $cust_pay->paynum;
910   }
911
912   return ''; #no error
913
914 }
915
916
917 # item _realtime_bop_result CUST_PAY_PENDING, BOP_OBJECT [ OPTION => VALUE ... ]
918
919 # Wraps up processing of a realtime credit card or ACH (electronic check)
920 # transaction.
921
922 sub _realtime_bop_result {
923   my( $self, $cust_pay_pending, $transaction, %options ) = @_;
924
925   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
926
927   if ( $DEBUG ) {
928     warn "$me _realtime_bop_result: pending transaction ".
929       $cust_pay_pending->paypendingnum. "\n";
930     warn "  $_ => $options{$_}\n" foreach keys %options;
931   }
932
933   my $payment_gateway = $options{payment_gateway}
934     or return "no payment gateway in arguments to _realtime_bop_result";
935
936   $cust_pay_pending->status($transaction->is_success() ? 'captured' : 'declined');
937   my $cpp_captured_err = $cust_pay_pending->replace; #also saves post-transaction tokenization, if that happens
938   return $cpp_captured_err if $cpp_captured_err;
939
940   if ( $transaction->is_success() ) {
941
942     my $order_number = $transaction->order_number
943       if $transaction->can('order_number');
944
945     my $cust_pay = new FS::cust_pay ( {
946        'custnum'  => $self->custnum,
947        'invnum'   => $options{'invnum'},
948        'paid'     => $cust_pay_pending->paid,
949        '_date'    => '',
950        'payby'    => $cust_pay_pending->payby,
951        'payinfo'  => $options{'payinfo'},
952        'paymask'  => $options{'paymask'} || $cust_pay_pending->paymask,
953        'paydate'  => $cust_pay_pending->paydate,
954        'pkgnum'   => $cust_pay_pending->pkgnum,
955        'discount_term'  => $options{'discount_term'},
956        'gatewaynum'     => ($payment_gateway->gatewaynum || ''),
957        'processor'      => $payment_gateway->gateway_module,
958        'auth'           => $transaction->authorization,
959        'order_number'   => $order_number || '',
960        'no_auto_apply'  => $options{'no_auto_apply'} ? 'Y' : '',
961     } );
962     #doesn't hurt to know, even though the dup check is in cust_pay_pending now
963     $cust_pay->payunique( $options{payunique} )
964       if defined($options{payunique}) && length($options{payunique});
965
966     my $oldAutoCommit = $FS::UID::AutoCommit;
967     local $FS::UID::AutoCommit = 0;
968     my $dbh = dbh;
969
970     #start a transaction, insert the cust_pay and set cust_pay_pending.status to done in a single transction
971
972     my $error = $cust_pay->insert($options{'manual'} ? ( 'manual' => 1 ) : () );
973
974     if ( $error ) {
975       $dbh->rollback or die $dbh->errstr if $oldAutoCommit;
976       $cust_pay->invnum(''); #try again with no specific invnum
977       $cust_pay->paynum('');
978       my $error2 = $cust_pay->insert( $options{'manual'} ?
979                                       ( 'manual' => 1 ) : ()
980                                     );
981       if ( $error2 ) {
982         # gah.  but at least we have a record of the state we had to abort in
983         # from cust_pay_pending now.
984         $dbh->rollback or die $dbh->errstr if $oldAutoCommit;
985         my $e = "WARNING: $options{method} captured but payment not recorded -".
986                 " error inserting payment (". $payment_gateway->gateway_module.
987                 "): $error2".
988                 " (previously tried insert with invnum #$options{'invnum'}" .
989                 ": $error ) - pending payment saved as paypendingnum ".
990                 $cust_pay_pending->paypendingnum. "\n";
991         warn $e;
992         return $e;
993       }
994     }
995
996     my $jobnum = $cust_pay_pending->jobnum;
997     if ( $jobnum ) {
998        my $placeholder = qsearchs( 'queue', { 'jobnum' => $jobnum } );
999       
1000        unless ( $placeholder ) {
1001          $dbh->rollback or die $dbh->errstr if $oldAutoCommit;
1002          my $e = "WARNING: $options{method} captured but job $jobnum not ".
1003              "found for paypendingnum ". $cust_pay_pending->paypendingnum. "\n";
1004          warn $e;
1005          return $e;
1006        }
1007
1008        $error = $placeholder->delete;
1009
1010        if ( $error ) {
1011          $dbh->rollback or die $dbh->errstr if $oldAutoCommit;
1012          my $e = "WARNING: $options{method} captured but could not delete ".
1013               "job $jobnum for paypendingnum ".
1014               $cust_pay_pending->paypendingnum. ": $error\n";
1015          warn $e;
1016          return $e;
1017        }
1018
1019        $cust_pay_pending->set('jobnum','');
1020
1021     }
1022     
1023     if ( $options{'paynum_ref'} ) {
1024       ${ $options{'paynum_ref'} } = $cust_pay->paynum;
1025     }
1026
1027     $cust_pay_pending->status('done');
1028     $cust_pay_pending->statustext('captured');
1029     $cust_pay_pending->paynum($cust_pay->paynum);
1030     my $cpp_done_err = $cust_pay_pending->replace;
1031
1032     if ( $cpp_done_err ) {
1033
1034       $dbh->rollback or die $dbh->errstr if $oldAutoCommit;
1035       my $e = "WARNING: $options{method} captured but payment not recorded - ".
1036               "error updating status for paypendingnum ".
1037               $cust_pay_pending->paypendingnum. ": $cpp_done_err \n";
1038       warn $e;
1039       return $e;
1040
1041     } else {
1042
1043       $dbh->commit or die $dbh->errstr if $oldAutoCommit;
1044
1045       if ( $options{'apply'} ) {
1046         my $apply_error = $self->apply_payments_and_credits;
1047         if ( $apply_error ) {
1048           warn "WARNING: error applying payment: $apply_error\n";
1049           #but we still should return no error cause the payment otherwise went
1050           #through...
1051         }
1052       }
1053
1054       # have a CC surcharge portion --> one-time charge
1055       if ( $options{'cc_surcharge'} > 0 ) { 
1056             # XXX: this whole block needs to be in a transaction?
1057
1058           my $invnum;
1059           $invnum = $options{'invnum'} if $options{'invnum'};
1060           unless ( $invnum ) { # probably from a payment screen
1061              # do we have any open invoices? pick earliest
1062              # uses the fact that cust_main->cust_bill sorts by date ascending
1063              my @open = $self->open_cust_bill;
1064              $invnum = $open[0]->invnum if scalar(@open);
1065           }
1066             
1067           unless ( $invnum ) {  # still nothing? pick last closed invoice
1068              # again uses fact that cust_main->cust_bill sorts by date ascending
1069              my @closed = $self->cust_bill;
1070              $invnum = $closed[$#closed]->invnum if scalar(@closed);
1071           }
1072
1073           unless ( $invnum ) {
1074             # XXX: unlikely case - pre-paying before any invoices generated
1075             # what it should do is create a new invoice and pick it
1076                 warn 'CC SURCHARGE AND NO INVOICES PICKED TO APPLY IT!';
1077                 return '';
1078           }
1079
1080           my $cust_pkg;
1081           my $charge_error = $self->charge({
1082                                     'amount'    => $options{'cc_surcharge'},
1083                                     'pkg'       => 'Credit Card Surcharge',
1084                                     'setuptax'  => 'Y',
1085                                     'cust_pkg_ref' => \$cust_pkg,
1086                                 });
1087           if($charge_error) {
1088                 warn 'Unable to add CC surcharge cust_pkg';
1089                 return '';
1090           }
1091
1092           $cust_pkg->setup(time);
1093           my $cp_error = $cust_pkg->replace;
1094           if($cp_error) {
1095               warn 'Unable to set setup time on cust_pkg for cc surcharge';
1096             # but keep going...
1097           }
1098                                     
1099           my $cust_bill = qsearchs('cust_bill', { 'invnum' => $invnum });
1100           unless ( $cust_bill ) {
1101               warn "race condition + invoice deletion just happened";
1102               return '';
1103           }
1104
1105           my $grand_error = 
1106             $cust_bill->add_cc_surcharge($cust_pkg->pkgnum,$options{'cc_surcharge'});
1107
1108           warn "cannot add CC surcharge to invoice #$invnum: $grand_error"
1109             if $grand_error;
1110       }
1111
1112       return ''; #no error
1113
1114     }
1115
1116   } else {
1117
1118     my $perror = $transaction->error_message;
1119     #$payment_gateway->gateway_module. " error: ".
1120     # removed for conciseness
1121
1122     my $jobnum = $cust_pay_pending->jobnum;
1123     if ( $jobnum ) {
1124        my $placeholder = qsearchs( 'queue', { 'jobnum' => $jobnum } );
1125       
1126        if ( $placeholder ) {
1127          my $error = $placeholder->depended_delete;
1128          $error ||= $placeholder->delete;
1129          $cust_pay_pending->set('jobnum','');
1130          warn "error removing provisioning jobs after declined paypendingnum ".
1131            $cust_pay_pending->paypendingnum. ": $error\n" if $error;
1132        } else {
1133          my $e = "error finding job $jobnum for declined paypendingnum ".
1134               $cust_pay_pending->paypendingnum. "\n";
1135          warn $e;
1136        }
1137
1138     }
1139     
1140     unless ( $transaction->error_message ) {
1141
1142       my $t_response;
1143       if ( $transaction->can('response_page') ) {
1144         $t_response = {
1145                         'page'    => ( $transaction->can('response_page')
1146                                          ? $transaction->response_page
1147                                          : ''
1148                                      ),
1149                         'code'    => ( $transaction->can('response_code')
1150                                          ? $transaction->response_code
1151                                          : ''
1152                                      ),
1153                         'headers' => ( $transaction->can('response_headers')
1154                                          ? $transaction->response_headers
1155                                          : ''
1156                                      ),
1157                       };
1158       } else {
1159         $t_response .=
1160           "No additional debugging information available for ".
1161             $payment_gateway->gateway_module;
1162       }
1163
1164       $perror .= "No error_message returned from ".
1165                    $payment_gateway->gateway_module. " -- ".
1166                  ( ref($t_response) ? Dumper($t_response) : $t_response );
1167
1168     }
1169
1170     if ( !$options{'quiet'} && !$realtime_bop_decline_quiet
1171          && $conf->exists('emaildecline', $self->agentnum)
1172          && grep { $_ ne 'POST' } $self->invoicing_list
1173          && ! grep { $transaction->error_message =~ /$_/ }
1174                    $conf->config('emaildecline-exclude', $self->agentnum)
1175     ) {
1176
1177       # Send a decline alert to the customer.
1178       my $msgnum = $conf->config('decline_msgnum', $self->agentnum);
1179       my $error = '';
1180       if ( $msgnum ) {
1181         # include the raw error message in the transaction state
1182         $cust_pay_pending->setfield('error', $transaction->error_message);
1183         my $msg_template = qsearchs('msg_template', { msgnum => $msgnum });
1184         $error = $msg_template->send( 'cust_main' => $self,
1185                                       'object'    => $cust_pay_pending );
1186       }
1187
1188
1189       $perror .= " (also received error sending decline notification: $error)"
1190         if $error;
1191
1192     }
1193
1194     $cust_pay_pending->status('done');
1195     $cust_pay_pending->statustext($perror);
1196     #'declined:': no, that's failure_status
1197     if ( $transaction->can('failure_status') ) {
1198       $cust_pay_pending->failure_status( $transaction->failure_status );
1199     }
1200     my $cpp_done_err = $cust_pay_pending->replace;
1201     if ( $cpp_done_err ) {
1202       my $e = "WARNING: $options{method} declined but pending payment not ".
1203               "resolved - error updating status for paypendingnum ".
1204               $cust_pay_pending->paypendingnum. ": $cpp_done_err \n";
1205       warn $e;
1206       $perror = "$e ($perror)";
1207     }
1208
1209     return $perror;
1210   }
1211
1212 }
1213
1214 =item realtime_botpp_capture CUST_PAY_PENDING [ OPTION => VALUE ... ]
1215
1216 Verifies successful third party processing of a realtime credit card or
1217 ACH (electronic check) transaction via a
1218 Business::OnlineThirdPartyPayment realtime gateway.  See
1219 L<http://420.am/business-onlinethirdpartypayment> for supported gateways.
1220
1221 Available options are: I<description>, I<invnum>, I<quiet>, I<paynum_ref>, I<payunique>
1222
1223 The additional options I<payname>, I<city>, I<state>,
1224 I<zip>, I<payinfo> and I<paydate> are also available.  Any of these options,
1225 if set, will override the value from the customer record.
1226
1227 I<description> is a free-text field passed to the gateway.  It defaults to
1228 "Internet services".
1229
1230 If an I<invnum> is specified, this payment (if successful) is applied to the
1231 specified invoice.  If you don't specify an I<invnum> you might want to
1232 call the B<apply_payments> method.
1233
1234 I<quiet> can be set true to surpress email decline notices.
1235
1236 I<paynum_ref> can be set to a scalar reference.  It will be filled in with the
1237 resulting paynum, if any.
1238
1239 I<payunique> is a unique identifier for this payment.
1240
1241 Returns a hashref containing elements bill_error (which will be undefined
1242 upon success) and session_id of any associated session.
1243
1244 =cut
1245
1246 sub realtime_botpp_capture {
1247   my( $self, $cust_pay_pending, %options ) = @_;
1248
1249   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
1250
1251   if ( $DEBUG ) {
1252     warn "$me realtime_botpp_capture: pending transaction $cust_pay_pending\n";
1253     warn "  $_ => $options{$_}\n" foreach keys %options;
1254   }
1255
1256   eval "use Business::OnlineThirdPartyPayment";  
1257   die $@ if $@;
1258
1259   ###
1260   # select the gateway
1261   ###
1262
1263   my $method = FS::payby->payby2bop($cust_pay_pending->payby);
1264
1265   my $payment_gateway;
1266   my $gatewaynum = $cust_pay_pending->getfield('gatewaynum');
1267   $payment_gateway = $gatewaynum ? qsearchs( 'payment_gateway',
1268                 { gatewaynum => $gatewaynum }
1269               )
1270     : $self->agent->payment_gateway( 'method' => $method,
1271                                      # 'invnum'  => $cust_pay_pending->invnum,
1272                                      # 'payinfo' => $cust_pay_pending->payinfo,
1273                                    );
1274
1275   $options{payment_gateway} = $payment_gateway; # for the helper subs
1276
1277   ###
1278   # massage data
1279   ###
1280
1281   my @invoicing_list = $self->invoicing_list_emailonly;
1282   if ( $conf->exists('emailinvoiceautoalways')
1283        || $conf->exists('emailinvoiceauto') && ! @invoicing_list
1284        || ( $conf->exists('emailinvoiceonly') && ! @invoicing_list ) ) {
1285     push @invoicing_list, $self->all_emails;
1286   }
1287
1288   my $email = ($conf->exists('business-onlinepayment-email-override'))
1289               ? $conf->config('business-onlinepayment-email-override')
1290               : $invoicing_list[0];
1291
1292   my %content = ();
1293
1294   $content{email_customer} = 
1295     (    $conf->exists('business-onlinepayment-email_customer')
1296       || $conf->exists('business-onlinepayment-email-override') );
1297       
1298   ###
1299   # run transaction(s)
1300   ###
1301
1302   my $transaction =
1303     new Business::OnlineThirdPartyPayment( $payment_gateway->gateway_module,
1304                                            _bop_options(\%options),
1305                                          );
1306
1307   $transaction->reference({ %options }); 
1308
1309   $transaction->content(
1310     'type'           => $method,
1311     _bop_auth(\%options),
1312     'action'         => 'Post Authorization',
1313     'description'    => $options{'description'},
1314     'amount'         => $cust_pay_pending->paid,
1315     #'invoice_number' => $options{'invnum'},
1316     'customer_id'    => $self->custnum,
1317     'reference'      => $cust_pay_pending->paypendingnum,
1318     'email'          => $email,
1319     'phone'          => $self->daytime || $self->night,
1320     %content, #after
1321     # plus whatever is required for bogus capture avoidance
1322   );
1323
1324   $transaction->submit();
1325
1326   my $error =
1327     $self->_realtime_bop_result( $cust_pay_pending, $transaction, %options );
1328
1329   if ( $options{'apply'} ) {
1330     my $apply_error = $self->apply_payments_and_credits;
1331     if ( $apply_error ) {
1332       warn "WARNING: error applying payment: $apply_error\n";
1333     }
1334   }
1335
1336   return {
1337     bill_error => $error,
1338     session_id => $cust_pay_pending->session_id,
1339   }
1340
1341 }
1342
1343 =item default_payment_gateway
1344
1345 DEPRECATED -- use agent->payment_gateway
1346
1347 =cut
1348
1349 sub default_payment_gateway {
1350   my( $self, $method ) = @_;
1351
1352   die "Real-time processing not enabled\n"
1353     unless $conf->exists('business-onlinepayment');
1354
1355   #warn "default_payment_gateway deprecated -- use agent->payment_gateway\n";
1356
1357   #load up config
1358   my $bop_config = 'business-onlinepayment';
1359   $bop_config .= '-ach'
1360     if $method =~ /^(ECHECK|CHEK)$/ && $conf->exists($bop_config. '-ach');
1361   my ( $processor, $login, $password, $action, @bop_options ) =
1362     $conf->config($bop_config);
1363   $action ||= 'normal authorization';
1364   pop @bop_options if scalar(@bop_options) % 2 && $bop_options[-1] =~ /^\s*$/;
1365   die "No real-time processor is enabled - ".
1366       "did you set the business-onlinepayment configuration value?\n"
1367     unless $processor;
1368
1369   ( $processor, $login, $password, $action, @bop_options )
1370 }
1371
1372 =item realtime_refund_bop METHOD [ OPTION => VALUE ... ]
1373
1374 Refunds a realtime credit card or ACH (electronic check) transaction
1375 via a Business::OnlinePayment realtime gateway.  See
1376 L<http://420.am/business-onlinepayment> for supported gateways.
1377
1378 Available methods are: I<CC> or I<ECHECK>
1379
1380 Available options are: I<amount>, I<reasonnum>, I<paynum>, I<paydate>
1381
1382 Most gateways require a reference to an original payment transaction to refund,
1383 so you probably need to specify a I<paynum>.
1384
1385 I<amount> defaults to the original amount of the payment if not specified.
1386
1387 I<reasonnum> specified an existing refund reason for the refund
1388
1389 I<paydate> specifies the expiration date for a credit card overriding the
1390 value from the customer record or the payment record. Specified as yyyy-mm-dd
1391
1392 Implementation note: If I<amount> is unspecified or equal to the amount of the
1393 orignal payment, first an attempt is made to "void" the transaction via
1394 the gateway (to cancel a not-yet settled transaction) and then if that fails,
1395 the normal attempt is made to "refund" ("credit") the transaction via the
1396 gateway is attempted. No attempt to "void" the transaction is made if the 
1397 gateway has introspection data and doesn't support void.
1398
1399 #The additional options I<payname>, I<address1>, I<address2>, I<city>, I<state>,
1400 #I<zip>, I<payinfo> and I<paydate> are also available.  Any of these options,
1401 #if set, will override the value from the customer record.
1402
1403 #If an I<invnum> is specified, this payment (if successful) is applied to the
1404 #specified invoice.  If you don't specify an I<invnum> you might want to
1405 #call the B<apply_payments> method.
1406
1407 =cut
1408
1409 #some false laziness w/realtime_bop, not enough to make it worth merging
1410 #but some useful small subs should be pulled out
1411 sub realtime_refund_bop {
1412   my $self = shift;
1413
1414   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
1415
1416   my %options = ();
1417   if (ref($_[0]) eq 'HASH') {
1418     %options = %{$_[0]};
1419   } else {
1420     my $method = shift;
1421     %options = @_;
1422     $options{method} = $method;
1423   }
1424
1425   if ( $DEBUG ) {
1426     warn "$me realtime_refund_bop (new): $options{method} refund\n";
1427     warn "  $_ => $options{$_}\n" foreach keys %options;
1428   }
1429
1430   return "No reason specified" unless $options{'reasonnum'} =~ /^\d+$/;
1431
1432   my %content = ();
1433
1434   ###
1435   # look up the original payment and optionally a gateway for that payment
1436   ###
1437
1438   my $cust_pay = '';
1439   my $amount = $options{'amount'};
1440
1441   my( $processor, $login, $password, @bop_options, $namespace ) ;
1442   my( $auth, $order_number ) = ( '', '', '' );
1443   my $gatewaynum = '';
1444
1445   if ( $options{'paynum'} ) {
1446
1447     warn "  paynum: $options{paynum}\n" if $DEBUG > 1;
1448     $cust_pay = qsearchs('cust_pay', { paynum=>$options{'paynum'} } )
1449       or return "Unknown paynum $options{'paynum'}";
1450     $amount ||= $cust_pay->paid;
1451
1452     my @cust_bill_pay = qsearch('cust_bill_pay', { paynum=>$cust_pay->paynum });
1453     $content{'invoice_number'} = $cust_bill_pay[0]->invnum if @cust_bill_pay;
1454
1455     if ( $cust_pay->get('processor') ) {
1456       ($gatewaynum, $processor, $auth, $order_number) =
1457       (
1458         $cust_pay->gatewaynum,
1459         $cust_pay->processor,
1460         $cust_pay->auth,
1461         $cust_pay->order_number,
1462       );
1463     } else {
1464       # this payment wasn't upgraded, which probably means this won't work,
1465       # but try it anyway
1466       $cust_pay->paybatch =~ /^((\d+)\-)?(\w+):\s*([\w\-\/ ]*)(:([\w\-]+))?$/
1467         or return "Can't parse paybatch for paynum $options{'paynum'}: ".
1468                   $cust_pay->paybatch;
1469       ( $gatewaynum, $processor, $auth, $order_number ) = ( $2, $3, $4, $6 );
1470     }
1471
1472     my $payment_gateway;
1473     if ( $gatewaynum ) { #gateway for the payment to be refunded
1474
1475       $payment_gateway =
1476         qsearchs('payment_gateway', { 'gatewaynum' => $gatewaynum } );
1477       die "payment gateway $gatewaynum not found"
1478         unless $payment_gateway;
1479
1480       $processor   = $payment_gateway->gateway_module;
1481       $login       = $payment_gateway->gateway_username;
1482       $password    = $payment_gateway->gateway_password;
1483       $namespace   = $payment_gateway->gateway_namespace;
1484       @bop_options = $payment_gateway->options;
1485
1486     } else { #try the default gateway
1487
1488       my $conf_processor;
1489       $payment_gateway =
1490         $self->agent->payment_gateway('method' => $options{method});
1491
1492       ( $conf_processor, $login, $password, $namespace ) =
1493         map { my $method = "gateway_$_"; $payment_gateway->$method }
1494           qw( module username password namespace );
1495
1496       @bop_options = $payment_gateway->gatewaynum
1497                        ? $payment_gateway->options
1498                        : @{ $payment_gateway->get('options') };
1499       my %bop_options = @bop_options;
1500
1501       return "processor of payment $options{'paynum'} $processor does not".
1502              " match default processor $conf_processor"
1503         unless ($processor eq $conf_processor)
1504             || (($conf_processor eq 'CardFortress') && ($processor eq $bop_options{'gateway'}));
1505
1506       $processor = $conf_processor;
1507
1508     }
1509
1510     # if gateway has switched to CardFortress but token_check hasn't run yet,
1511     # tokenize just this record now, so that token gets passed/set appropriately
1512     if ($cust_pay->payby eq 'CARD' && !$cust_pay->tokenized) {
1513       my %tokenopts = (
1514         'payment_gateway' => $payment_gateway,
1515         'method'          => 'CC',
1516         'payinfo'         => $cust_pay->payinfo,
1517         'paydate'         => $cust_pay->paydate,
1518       );
1519       my $error = $self->realtime_tokenize(\%tokenopts); # no-op unless gateway can tokenize
1520       if ($self->tokenized($tokenopts{'payinfo'})) { # implies no error
1521         warn "  tokenizing cust_pay\n" if $DEBUG > 1;
1522         $cust_pay->payinfo($tokenopts{'payinfo'});
1523         $error = $cust_pay->replace;
1524       }
1525       return $error if $error;
1526     }
1527
1528   } else { # didn't specify a paynum, so look for agent gateway overrides
1529            # like a normal transaction 
1530  
1531     my $payment_gateway =
1532       $self->agent->payment_gateway( 'method'  => $options{method} );
1533     my( $processor, $login, $password, $namespace ) =
1534       map { my $method = "gateway_$_"; $payment_gateway->$method }
1535         qw( module username password namespace );
1536
1537     my @bop_options = $payment_gateway->gatewaynum
1538                         ? $payment_gateway->options
1539                         : @{ $payment_gateway->get('options') };
1540
1541   }
1542   return "neither amount nor paynum specified" unless $amount;
1543
1544   eval "use $namespace";  
1545   die $@ if $@;
1546
1547   %content = (
1548     %content,
1549     'type'           => $options{method},
1550     'login'          => $login,
1551     'password'       => $password,
1552     'order_number'   => $order_number,
1553     'amount'         => $amount,
1554   );
1555   $content{authorization} = $auth
1556     if length($auth); #echeck/ACH transactions have an order # but no auth
1557                       #(at least with authorize.net)
1558
1559   my $currency =    $conf->exists('business-onlinepayment-currency')
1560                  && $conf->config('business-onlinepayment-currency');
1561   $content{currency} = $currency if $currency;
1562
1563   my $disable_void_after;
1564   if ($conf->exists('disable_void_after')
1565       && $conf->config('disable_void_after') =~ /^(\d+)$/) {
1566     $disable_void_after = $1;
1567   }
1568
1569   #first try void if applicable
1570   my $void = new Business::OnlinePayment( $processor, @bop_options );
1571
1572   my $tryvoid = 1;
1573   if ($void->can('info')) {
1574       my $paytype = '';
1575       $paytype = 'ECHECK' if $cust_pay && $cust_pay->payby eq 'CHEK';
1576       $paytype = 'CC' if $cust_pay && $cust_pay->payby eq 'CARD';
1577       my %supported_actions = $void->info('supported_actions');
1578       $tryvoid = 0 
1579         if ( %supported_actions && $paytype 
1580                 && defined($supported_actions{$paytype}) 
1581                 && !grep{ $_ eq 'Void' } @{$supported_actions{$paytype}} );
1582   }
1583
1584   if ( $cust_pay && $cust_pay->paid == $amount
1585     && (
1586       ( not defined($disable_void_after) )
1587       || ( time < ($cust_pay->_date + $disable_void_after ) )
1588     )
1589     && $tryvoid
1590   ) {
1591     warn "  attempting void\n" if $DEBUG > 1;
1592     if ( $void->can('info') ) {
1593       if ( $cust_pay->payby eq 'CARD'
1594            && $void->info('CC_void_requires_card') )
1595       {
1596         $content{'card_number'} = $cust_pay->payinfo;
1597       } elsif ( $cust_pay->payby eq 'CHEK'
1598                 && $void->info('ECHECK_void_requires_account') )
1599       {
1600         ( $content{'account_number'}, $content{'routing_code'} ) =
1601           split('@', $cust_pay->payinfo);
1602         $content{'name'} = $self->get('first'). ' '. $self->get('last');
1603       }
1604     }
1605     $void->content( 'action' => 'void', %content );
1606     $void->test_transaction(1)
1607       if $conf->exists('business-onlinepayment-test_transaction');
1608     $void->submit();
1609     if ( $void->is_success ) {
1610       # specified as a refund reason, but now we want a payment void reason
1611       # extract just the reason text, let cust_pay::void handle new_or_existing
1612       my $reason = qsearchs('reason',{ 'reasonnum' => $options{'reasonnum'} });
1613       my $error;
1614       $error = 'Reason could not be loaded' unless $reason;      
1615       $error = $cust_pay->void($reason->reason) unless $error;
1616       if ( $error ) {
1617         # gah, even with transactions.
1618         my $e = 'WARNING: Card/ACH voided but database not updated - '.
1619                 "error voiding payment: $error";
1620         warn $e;
1621         return $e;
1622       }
1623       warn "  void successful\n" if $DEBUG > 1;
1624       return '';
1625     }
1626   }
1627
1628   warn "  void unsuccessful, trying refund\n"
1629     if $DEBUG > 1;
1630
1631   #massage data
1632   my $address = $self->address1;
1633   $address .= ", ". $self->address2 if $self->address2;
1634
1635   my($payname, $payfirst, $paylast);
1636   if ( $self->payname && $options{method} ne 'ECHECK' ) {
1637     $payname = $self->payname;
1638     $payname =~ /^\s*([\w \,\.\-\']*)?\s+([\w\,\.\-\']+)\s*$/
1639       or return "Illegal payname $payname";
1640     ($payfirst, $paylast) = ($1, $2);
1641   } else {
1642     $payfirst = $self->getfield('first');
1643     $paylast = $self->getfield('last');
1644     $payname =  "$payfirst $paylast";
1645   }
1646
1647   my @invoicing_list = $self->invoicing_list_emailonly;
1648   if ( $conf->exists('emailinvoiceautoalways')
1649        || $conf->exists('emailinvoiceauto') && ! @invoicing_list
1650        || ( $conf->exists('emailinvoiceonly') && ! @invoicing_list ) ) {
1651     push @invoicing_list, $self->all_emails;
1652   }
1653
1654   my $email = ($conf->exists('business-onlinepayment-email-override'))
1655               ? $conf->config('business-onlinepayment-email-override')
1656               : $invoicing_list[0];
1657
1658   my $payip = exists($options{'payip'})
1659                 ? $options{'payip'}
1660                 : $self->payip;
1661   $content{customer_ip} = $payip
1662     if length($payip);
1663
1664   my $payinfo = '';
1665   my $paymask = ''; # for refund record
1666   if ( $options{method} eq 'CC' ) {
1667
1668     if ( $cust_pay ) {
1669       $content{card_number} = $payinfo = $cust_pay->payinfo;
1670       $paymask = $cust_pay->paymask;
1671       (exists($options{'paydate'}) ? $options{'paydate'} : $cust_pay->paydate)
1672         =~ /^\d{2}(\d{2})[\/\-](\d+)[\/\-]\d+$/ &&
1673         ($content{expiration} = "$2/$1");  # where available
1674     } else {
1675       # this really needs a better cleanup
1676       die "Refund without paynum not supported";
1677 #      $content{card_number} = $payinfo = $self->payinfo;
1678 #      (exists($options{'paydate'}) ? $options{'paydate'} : $self->paydate)
1679 #        =~ /^\d{2}(\d{2})[\/\-](\d+)[\/\-]\d+$/;
1680 #      $content{expiration} = "$2/$1";
1681     }
1682
1683   } elsif ( $options{method} eq 'ECHECK' ) {
1684
1685     if ( $cust_pay ) {
1686       $payinfo = $cust_pay->payinfo;
1687     } else {
1688       $payinfo = $self->payinfo;
1689     } 
1690     ( $content{account_number}, $content{routing_code} )= split('@', $payinfo );
1691     $content{bank_name} = $self->payname;
1692     $content{account_type} = 'CHECKING';
1693     $content{account_name} = $payname;
1694     $content{customer_org} = $self->company ? 'B' : 'I';
1695     $content{customer_ssn} = $self->ss;
1696
1697   }
1698
1699   #then try refund
1700   my $refund = new Business::OnlinePayment( $processor, @bop_options );
1701   my %sub_content = $refund->content(
1702     'action'         => 'credit',
1703     'customer_id'    => $self->custnum,
1704     'last_name'      => $paylast,
1705     'first_name'     => $payfirst,
1706     'name'           => $payname,
1707     'address'        => $address,
1708     'city'           => $self->city,
1709     'state'          => $self->state,
1710     'zip'            => $self->zip,
1711     'country'        => $self->country,
1712     'email'          => $email,
1713     'phone'          => $self->daytime || $self->night,
1714     %content, #after
1715   );
1716   warn join('', map { "  $_ => $sub_content{$_}\n" } keys %sub_content )
1717     if $DEBUG > 1;
1718   $refund->test_transaction(1)
1719     if $conf->exists('business-onlinepayment-test_transaction');
1720   $refund->submit();
1721
1722   return "$processor error: ". $refund->error_message
1723     unless $refund->is_success();
1724
1725   $order_number = $refund->order_number if $refund->can('order_number');
1726
1727   # change this to just use $cust_pay->delete_cust_bill_pay?
1728   while ( $cust_pay && $cust_pay->unapplied < $amount ) {
1729     my @cust_bill_pay = $cust_pay->cust_bill_pay;
1730     last unless @cust_bill_pay;
1731     my $cust_bill_pay = pop @cust_bill_pay;
1732     my $error = $cust_bill_pay->delete;
1733     last if $error;
1734   }
1735
1736   my $cust_refund = new FS::cust_refund ( {
1737     'custnum'  => $self->custnum,
1738     'paynum'   => $options{'paynum'},
1739     'source_paynum' => $options{'paynum'},
1740     'refund'   => $amount,
1741     '_date'    => '',
1742     'payby'    => $bop_method2payby{$options{method}},
1743     'payinfo'  => $payinfo,
1744     'paymask'  => $paymask,
1745     'reasonnum'     => $options{'reasonnum'},
1746     'gatewaynum'    => $gatewaynum, # may be null
1747     'processor'     => $processor,
1748     'auth'          => $refund->authorization,
1749     'order_number'  => $order_number,
1750   } );
1751   my $error = $cust_refund->insert;
1752   if ( $error ) {
1753     $cust_refund->paynum(''); #try again with no specific paynum
1754     $cust_refund->source_paynum('');
1755     my $error2 = $cust_refund->insert;
1756     if ( $error2 ) {
1757       # gah, even with transactions.
1758       my $e = 'WARNING: Card/ACH refunded but database not updated - '.
1759               "error inserting refund ($processor): $error2".
1760               " (previously tried insert with paynum #$options{'paynum'}" .
1761               ": $error )";
1762       warn $e;
1763       return $e;
1764     }
1765   }
1766
1767   ''; #no error
1768
1769 }
1770
1771 =item realtime_verify_bop [ OPTION => VALUE ... ]
1772
1773 Runs an authorization-only transaction for $1 against this credit card (if
1774 successful, immediatly reverses the authorization).
1775
1776 Returns the empty string if the authorization was sucessful, or an error
1777 message otherwise.
1778
1779 Option I<cust_payby> should be passed, even if it's not yet been inserted.
1780 Object will be tokenized if possible, but that change will not be
1781 updated in database (must be inserted/replaced afterwards.)
1782
1783 Currently only succeeds for Business::OnlinePayment CC transactions.
1784
1785 =cut
1786
1787 #some false laziness w/realtime_bop and realtime_refund_bop, not enough to make
1788 #it worth merging but some useful small subs should be pulled out
1789 sub realtime_verify_bop {
1790   my $self = shift;
1791
1792   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
1793   my $log = FS::Log->new('FS::cust_main::Billing_Realtime::realtime_verify_bop');
1794
1795   my %options = ();
1796   if (ref($_[0]) eq 'HASH') {
1797     %options = %{$_[0]};
1798   } else {
1799     %options = @_;
1800   }
1801
1802   if ( $DEBUG ) {
1803     warn "$me realtime_verify_bop\n";
1804     warn "  $_ => $options{$_}\n" foreach keys %options;
1805   }
1806
1807   # set fields from passed cust_payby
1808   return "No cust_payby" unless $options{'cust_payby'};
1809   _bop_cust_payby_options(\%options);
1810
1811   # check for banned credit card/ACH
1812   my $ban = FS::banned_pay->ban_search(
1813     'payby'   => $bop_method2payby{'CC'},
1814     'payinfo' => $options{payinfo},
1815   );
1816   return "Banned credit card" if $ban && $ban->bantype ne 'warn';
1817
1818   # possibly run a separate transaction to tokenize card number,
1819   #   so that we never store tokenized card info in cust_pay_pending
1820   if (($options{method} eq 'CC') && !$self->tokenized($options{'payinfo'})) {
1821     my $token_error = $self->realtime_tokenize(\%options);
1822     return $token_error if $token_error;
1823     #important that we not replace cust_payby here,
1824     #because cust_payby->replace uses realtime_verify_bop!
1825   }
1826
1827   ###
1828   # select a gateway
1829   ###
1830
1831   my $payment_gateway =  $self->_payment_gateway( \%options );
1832   my $namespace = $payment_gateway->gateway_namespace;
1833
1834   eval "use $namespace";  
1835   die $@ if $@;
1836
1837   ###
1838   # massage data
1839   ###
1840
1841   my $bop_content = $self->_bop_content(\%options);
1842   return $bop_content unless ref($bop_content);
1843
1844   my @invoicing_list = $self->invoicing_list_emailonly;
1845   if ( $conf->exists('emailinvoiceautoalways')
1846        || $conf->exists('emailinvoiceauto') && ! @invoicing_list
1847        || ( $conf->exists('emailinvoiceonly') && ! @invoicing_list ) ) {
1848     push @invoicing_list, $self->all_emails;
1849   }
1850
1851   my $email = ($conf->exists('business-onlinepayment-email-override'))
1852               ? $conf->config('business-onlinepayment-email-override')
1853               : $invoicing_list[0];
1854
1855   my $paydate = '';
1856   my %content = ();
1857
1858   if ( $namespace eq 'Business::OnlinePayment' ) {
1859
1860     if ( $options{method} eq 'CC' ) {
1861
1862       $content{card_number} = $options{payinfo};
1863       $paydate = $options{'paydate'};
1864       $paydate =~ /^\d{2}(\d{2})[\/\-](\d+)[\/\-]\d+$/;
1865       $content{expiration} = "$2/$1";
1866
1867       $content{cvv2} = $options{'paycvv'}
1868         if length($options{'paycvv'});
1869
1870       my $paystart_month = $options{'paystart_month'};
1871       my $paystart_year  = $options{'paystart_year'};
1872
1873       $content{card_start} = "$paystart_month/$paystart_year"
1874         if $paystart_month && $paystart_year;
1875
1876       my $payissue       = $options{'payissue'};
1877       $content{issue_number} = $payissue if $payissue;
1878
1879     } elsif ( $options{method} eq 'ECHECK' ){
1880       #cannot verify, move along (though it shouldn't be called...)
1881       return '';
1882     } else {
1883       return "unknown method ". $options{method};
1884     }
1885   } elsif ( $namespace eq 'Business::OnlineThirdPartyPayment' ) {
1886     #cannot verify, move along
1887     return '';
1888   } else {
1889     return "unknown namespace $namespace";
1890   }
1891
1892   ###
1893   # run transaction(s)
1894   ###
1895
1896   my $error;
1897   my $transaction; #need this back so we can do _tokenize_card
1898
1899   # don't mutex the customer here, because they might be uncommitted. and
1900   # this is only verification. it doesn't matter if they have other
1901   # unfinished verifications.
1902
1903   my $cust_pay_pending = new FS::cust_pay_pending {
1904     'custnum_pending'   => 1,
1905     'paid'              => '1.00',
1906     '_date'             => '',
1907     'payby'             => $bop_method2payby{'CC'},
1908     'payinfo'           => $options{payinfo},
1909     'paymask'           => $options{paymask},
1910     'paydate'           => $paydate,
1911     'pkgnum'            => $options{'pkgnum'},
1912     'status'            => 'new',
1913     'gatewaynum'        => $payment_gateway->gatewaynum || '',
1914     'session_id'        => $options{session_id} || '',
1915   };
1916   $cust_pay_pending->payunique( $options{payunique} )
1917     if defined($options{payunique}) && length($options{payunique});
1918
1919   IMMEDIATE: {
1920     # open a separate handle for creating/updating the cust_pay_pending
1921     # record
1922     local $FS::UID::dbh = myconnect();
1923     local $FS::UID::AutoCommit = 1;
1924
1925     # if this is an existing customer (and we can tell now because
1926     # this is a fresh transaction), it's safe to assign their custnum
1927     # to the cust_pay_pending record, and then the verification attempt
1928     # will remain linked to them even if it fails.
1929     if ( FS::cust_main->by_key($self->custnum) ) {
1930       $cust_pay_pending->set('custnum', $self->custnum);
1931     }
1932
1933     warn "inserting cust_pay_pending record for customer ". $self->custnum. "\n"
1934       if $DEBUG > 1;
1935
1936     # if this fails, just return; everything else will still allow the
1937     # cust_pay_pending to have its custnum set later
1938     my $cpp_new_err = $cust_pay_pending->insert;
1939     return $cpp_new_err if $cpp_new_err;
1940
1941     warn "inserted cust_pay_pending record for customer ". $self->custnum. "\n"
1942       if $DEBUG > 1;
1943     warn Dumper($cust_pay_pending) if $DEBUG > 2;
1944
1945     $transaction = new $namespace( $payment_gateway->gateway_module,
1946                                    _bop_options(\%options),
1947                                     );
1948
1949     $transaction->content(
1950       'type'           => 'CC',
1951       _bop_auth(\%options),          
1952       'action'         => 'Authorization Only',
1953       'description'    => $options{'description'},
1954       'amount'         => '1.00',
1955       'customer_id'    => $self->custnum,
1956       %$bop_content,
1957       'reference'      => $cust_pay_pending->paypendingnum, #for now
1958       'email'          => $email,
1959       %content, #after
1960     );
1961
1962     $cust_pay_pending->status('pending');
1963     my $cpp_pending_err = $cust_pay_pending->replace;
1964     return $cpp_pending_err if $cpp_pending_err;
1965
1966     warn Dumper($transaction) if $DEBUG > 2;
1967
1968     unless ( $BOP_TESTING ) {
1969       $transaction->test_transaction(1)
1970         if $conf->exists('business-onlinepayment-test_transaction');
1971       $transaction->submit();
1972     } else {
1973       if ( $BOP_TESTING_SUCCESS ) {
1974         $transaction->is_success(1);
1975         $transaction->authorization('fake auth');
1976       } else {
1977         $transaction->is_success(0);
1978         $transaction->error_message('fake failure');
1979       }
1980     }
1981
1982     if ( $transaction->is_success() ) {
1983
1984       $cust_pay_pending->status('authorized');
1985       my $cpp_authorized_err = $cust_pay_pending->replace;
1986       return $cpp_authorized_err if $cpp_authorized_err;
1987
1988       my $auth = $transaction->authorization;
1989       my $ordernum = $transaction->can('order_number')
1990                      ? $transaction->order_number
1991                      : '';
1992
1993       my $reverse = new $namespace( $payment_gateway->gateway_module,
1994                                     _bop_options(\%options),
1995                                   );
1996
1997       $reverse->content( 'action'        => 'Reverse Authorization',
1998                          _bop_auth(\%options),          
1999
2000                          # B:OP
2001                          'amount'        => '1.00',
2002                          'authorization' => $transaction->authorization,
2003                          'order_number'  => $ordernum,
2004
2005                          # vsecure
2006                          'result_code'   => $transaction->result_code,
2007                          'txn_date'      => $transaction->txn_date,
2008
2009                          %content,
2010                        );
2011       $reverse->test_transaction(1)
2012         if $conf->exists('business-onlinepayment-test_transaction');
2013       $reverse->submit();
2014
2015       if ( $reverse->is_success ) {
2016
2017         $cust_pay_pending->status('done');
2018         $cust_pay_pending->statustext('reversed');
2019         my $cpp_reversed_err = $cust_pay_pending->replace;
2020         return $cpp_reversed_err if $cpp_reversed_err;
2021
2022       } else {
2023
2024         my $e = "Authorization successful but reversal failed, custnum #".
2025                 $self->custnum. ': '.  $reverse->result_code.
2026                 ": ". $reverse->error_message;
2027         $log->warning($e);
2028         warn $e;
2029         return $e;
2030
2031       }
2032
2033       ### Address Verification ###
2034       #
2035       # Single-letter codes vary by cardtype.
2036       #
2037       # Erring on the side of accepting cards if avs is not available,
2038       # only rejecting if avs occurred and there's been an explicit mismatch
2039       #
2040       # Charts below taken from vSecure documentation,
2041       #    shows codes for Amex/Dscv/MC/Visa
2042       #
2043       # ACCEPTABLE AVS RESPONSES:
2044       # Both Address and 5-digit postal code match Y A Y Y
2045       # Both address and 9-digit postal code match Y A X Y
2046       # United Kingdom – Address and postal code match _ _ _ F
2047       # International transaction – Address and postal code match _ _ _ D/M
2048       #
2049       # ACCEPTABLE, BUT ISSUE A WARNING:
2050       # Ineligible transaction; or message contains a content error _ _ _ E
2051       # System unavailable; retry R U R R
2052       # Information unavailable U W U U
2053       # Issuer does not support AVS S U S S
2054       # AVS is not applicable _ _ _ S
2055       # Incompatible formats – Not verified _ _ _ C
2056       # Incompatible formats – Address not verified; postal code matches _ _ _ P
2057       # International transaction – address not verified _ G _ G/I
2058       #
2059       # UNACCEPTABLE AVS RESPONSES:
2060       # Only Address matches A Y A A
2061       # Only 5-digit postal code matches Z Z Z Z
2062       # Only 9-digit postal code matches Z Z W W
2063       # Neither address nor postal code matches N N N N
2064
2065       if (my $avscode = uc($transaction->avs_code)) {
2066
2067         # map codes to accept/warn/reject
2068         my $avs = {
2069           'American Express card' => {
2070             'A' => 'r',
2071             'N' => 'r',
2072             'R' => 'w',
2073             'S' => 'w',
2074             'U' => 'w',
2075             'Y' => 'a',
2076             'Z' => 'r',
2077           },
2078           'Discover card' => {
2079             'A' => 'a',
2080             'G' => 'w',
2081             'N' => 'r',
2082             'U' => 'w',
2083             'W' => 'w',
2084             'Y' => 'r',
2085             'Z' => 'r',
2086           },
2087           'MasterCard' => {
2088             'A' => 'r',
2089             'N' => 'r',
2090             'R' => 'w',
2091             'S' => 'w',
2092             'U' => 'w',
2093             'W' => 'r',
2094             'X' => 'a',
2095             'Y' => 'a',
2096             'Z' => 'r',
2097           },
2098           'VISA card' => {
2099             'A' => 'r',
2100             'C' => 'w',
2101             'D' => 'a',
2102             'E' => 'w',
2103             'F' => 'a',
2104             'G' => 'w',
2105             'I' => 'w',
2106             'M' => 'a',
2107             'N' => 'r',
2108             'P' => 'w',
2109             'R' => 'w',
2110             'S' => 'w',
2111             'U' => 'w',
2112             'W' => 'r',
2113             'Y' => 'a',
2114             'Z' => 'r',
2115           },
2116         };
2117         my $cardtype = cardtype($content{card_number});
2118         if ($avs->{$cardtype}) {
2119           my $avsact = $avs->{$cardtype}->{$avscode};
2120           my $warning = '';
2121           if ($avsact eq 'r') {
2122             return "AVS code verification failed, cardtype $cardtype, code $avscode";
2123           } elsif ($avsact eq 'w') {
2124             $warning = "AVS did not occur, cardtype $cardtype, code $avscode";
2125           } elsif (!$avsact) {
2126             $warning = "AVS code unknown, cardtype $cardtype, code $avscode";
2127           } # else $avsact eq 'a'
2128           if ($warning) {
2129             $log->warning($warning);
2130             warn $warning;
2131           }
2132         } # else $cardtype avs handling not implemented
2133       } # else !$transaction->avs_code
2134
2135     } else { # is not success
2136
2137       # status is 'done' not 'declined', as in _realtime_bop_result
2138       $cust_pay_pending->status('done');
2139       $error = $transaction->error_message || 'Unknown error';
2140       $cust_pay_pending->statustext($error);
2141       # could also record failure_status here,
2142       #   but it's not supported by B::OP::vSecureProcessing...
2143       #   need a B::OP module with (reverse) auth only to test it with
2144       my $cpp_declined_err = $cust_pay_pending->replace;
2145       return $cpp_declined_err if $cpp_declined_err;
2146
2147     }
2148
2149   } # end of IMMEDIATE; we now have our $error and $transaction
2150
2151   ###
2152   # Save the custnum (as part of the main transaction, so it can reference
2153   # the cust_main)
2154   ###
2155
2156   if (!$cust_pay_pending->custnum) {
2157     $cust_pay_pending->set('custnum', $self->custnum);
2158     my $set_custnum_err = $cust_pay_pending->replace;
2159     if ($set_custnum_err) {
2160       $log->error($set_custnum_err);
2161       $error ||= $set_custnum_err;
2162       # but if there was a real verification error also, return that one
2163     }
2164   }
2165
2166   ###
2167   # remove paycvv here?  need to find out if a reversed auth
2168   #   counts as an initial transaction for paycvv retention requirements
2169   ###
2170
2171   ###
2172   # Tokenize
2173   ###
2174
2175   # This block will only run if the B::OP module supports card_token but not the Tokenize transaction;
2176   #   if that never happens, we should get rid of it (as it has the potential to store real card numbers on error)
2177   if (my $card_token = $self->_tokenize_card($transaction,\%options)) {
2178     $cust_pay_pending->payinfo($card_token);
2179     my $cpp_token_err = $cust_pay_pending->replace;
2180     #this leaves real card number in cust_pay_pending, but can't do much else if cpp won't replace
2181     return $cpp_token_err if $cpp_token_err;
2182     #important that we not replace cust_payby here,
2183     #because cust_payby->replace uses realtime_verify_bop!
2184   }
2185
2186   ###
2187   # result handling
2188   ###
2189
2190   # $error contains the transaction error_message, if is_success was false.
2191  
2192   return $error;
2193
2194 }
2195
2196 =item realtime_tokenize [ OPTION => VALUE ... ]
2197
2198 If possible and necessary, runs a tokenize transaction.
2199 In order to be possible, a credit card cust_payby record
2200 must be passed and a Business::OnlinePayment gateway capable
2201 of Tokenize transactions must be configured for this user.
2202 Is only necessary if payinfo is not yet tokenized.
2203
2204 Returns the empty string if the authorization was sucessful
2205 or was not possible/necessary (thus allowing this to be safely called with
2206 non-tokenizable records/gateways, without having to perform separate tests),
2207 or an error message otherwise.
2208
2209 Option I<cust_payby> may be passed, even if it's not yet been inserted.
2210 Object will be tokenized if possible, but that change will not be
2211 updated in database (must be inserted/replaced afterwards.)
2212
2213 Otherwise, options I<method>, I<payinfo> and other cust_payby fields
2214 may be passed.  If options are passed as a hashref, I<payinfo>
2215 will be updated as appropriate in the passed hashref.
2216
2217 Can be run as a class method if option I<payment_gateway> is passed,
2218 but default customer id/name/phone can't be set in that case.  This
2219 is really only intended for tokenizing old records on upgrade.
2220
2221 =cut
2222
2223 # careful--might be run as a class method
2224 sub realtime_tokenize {
2225   my $self = shift;
2226
2227   local($DEBUG) = $FS::cust_main::DEBUG if $FS::cust_main::DEBUG > $DEBUG;
2228   my $log = FS::Log->new('FS::cust_main::Billing_Realtime::realtime_tokenize');
2229
2230   my %options = ();
2231   my $outoptions; #for returning cust_payby/payinfo
2232   if (ref($_[0]) eq 'HASH') {
2233     %options = %{$_[0]};
2234     $outoptions = $_[0];
2235   } else {
2236     %options = @_;
2237     $outoptions = \%options;
2238   }
2239
2240   # set fields from passed cust_payby
2241   _bop_cust_payby_options(\%options);
2242   return '' unless $options{method} eq 'CC';
2243   return '' if $self->tokenized($options{payinfo}); #already tokenized
2244
2245   # check for banned credit card/ACH
2246   my $ban = FS::banned_pay->ban_search(
2247     'payby'   => $bop_method2payby{'CC'},
2248     'payinfo' => $options{payinfo},
2249   );
2250   return "Banned credit card" if $ban && $ban->bantype ne 'warn';
2251
2252   ###
2253   # select a gateway
2254   ###
2255
2256   $options{'nofatal'} = 1;
2257   my $payment_gateway =  $self->_payment_gateway( \%options );
2258   return '' unless $payment_gateway;
2259   my $namespace = $payment_gateway->gateway_namespace;
2260   return '' unless $namespace eq 'Business::OnlinePayment';
2261
2262   eval "use $namespace";  
2263   return $@ if $@;
2264
2265   ###
2266   # check for tokenize ability
2267   ###
2268
2269   my $transaction = new $namespace( $payment_gateway->gateway_module,
2270                                     _bop_options(\%options),
2271                                   );
2272
2273   return '' unless $transaction->can('info');
2274
2275   my %supported_actions = $transaction->info('supported_actions');
2276   return '' unless $supported_actions{'CC'}
2277                 && grep /^Tokenize$/, @{$supported_actions{'CC'}};
2278
2279   ###
2280   # massage data
2281   ###
2282
2283   ### Currently, cardfortress only keys in on card number and exp date.
2284   ### We pass everything we'd pass to a normal transaction,
2285   ### for ease of current and future development,
2286   ### but note, when tokenizing old records, we may only have access to payinfo/paydate
2287
2288   my $bop_content = $self->_bop_content(\%options);
2289   return $bop_content unless ref($bop_content);
2290
2291   my $paydate = '';
2292   my %content = ();
2293
2294   $content{card_number} = $options{payinfo};
2295   $paydate = $options{'paydate'};
2296   $paydate =~ /^\d{2}(\d{2})[\/\-](\d+)[\/\-]\d+$/;
2297   $content{expiration} = "$2/$1";
2298
2299   $content{cvv2} = $options{'paycvv'}
2300     if length($options{'paycvv'});
2301
2302   my $paystart_month = $options{'paystart_month'};
2303   my $paystart_year  = $options{'paystart_year'};
2304
2305   $content{card_start} = "$paystart_month/$paystart_year"
2306     if $paystart_month && $paystart_year;
2307
2308   my $payissue       = $options{'payissue'};
2309   $content{issue_number} = $payissue if $payissue;
2310
2311   $content{customer_id} = $self->custnum
2312     if ref($self);
2313
2314   ###
2315   # run transaction
2316   ###
2317
2318   my $error;
2319
2320   # no cust_pay_pending---this is not a financial transaction
2321
2322   $transaction->content(
2323     'type'           => 'CC',
2324     _bop_auth(\%options),          
2325     'action'         => 'Tokenize',
2326     'description'    => $options{'description'},
2327     %$bop_content,
2328     %content, #after
2329   );
2330
2331   # no $BOP_TESTING handling for this
2332   $transaction->test_transaction(1)
2333     if $conf->exists('business-onlinepayment-test_transaction');
2334   $transaction->submit();
2335
2336   if ( $transaction->card_token() ) { # no is_success flag
2337
2338     # realtime_tokenize should not clear paycvv at this time.  it might be
2339     # needed for the first transaction, and a tokenize isn't actually a
2340     # transaction that hits the gateway.  at some point in the future, card
2341     # fortress should take on the "store paycvv until first transaction"
2342     # functionality and we should fix this in freeside, but i that's a bigger
2343     # project for another time.
2344
2345     #important that we not replace cust_payby here, 
2346     #because cust_payby->replace uses realtime_tokenize!
2347     $self->_tokenize_card($transaction,$outoptions);
2348
2349   } else {
2350
2351     $error = $transaction->error_message || 'Unknown error when tokenizing card';
2352
2353   }
2354
2355   return $error;
2356
2357 }
2358
2359
2360 =item tokenized PAYINFO
2361
2362 Convenience wrapper for L<FS::payinfo_Mixin/tokenized>
2363
2364 PAYINFO is required.
2365
2366 Can be run as class or object method, never loads from object.
2367
2368 =cut
2369
2370 sub tokenized {
2371   my $this = shift;
2372   my $payinfo = shift;
2373   FS::cust_pay->tokenized($payinfo);
2374 }
2375
2376 =item token_check [ quiet => 1, queue => 1, daily => 1 ]
2377
2378 NOT A METHOD.  Acts on all customers.  Placed here because it makes
2379 use of module-internal methods, and to keep everything that uses
2380 Billing::OnlinePayment all in one place.
2381
2382 Tokenizes all tokenizable card numbers from payinfo in cust_payby and 
2383 CARD transactions in cust_pay_pending, cust_pay, cust_pay_void and cust_refund.
2384
2385 If the I<queue> flag is set, newly tokenized records will be immediately
2386 committed, regardless of AutoCommit, so as to release the mutex on the record.
2387
2388 If all configured gateways have the ability to tokenize, detection of an 
2389 untokenizable record will cause a fatal error.  However, if the I<queue> flag 
2390 is set, this will instead cause a critical error to be recorded in the log, 
2391 and any other tokenizable records will still be committed.
2392
2393 If the I<daily> flag is also set, detection of existing untokenized records will 
2394 record an info message in the system log (because they should have never appeared 
2395 in the first place.)  Tokenization will still be attempted.
2396
2397 If any configured gateways do NOT have the ability to tokenize, or if a
2398 default gateway is not configured, then untokenized records are not considered 
2399 a threat, and no critical errors will be generated in the log.
2400
2401 =cut
2402
2403 sub token_check {
2404   #acts on all customers
2405   my %opt = @_;
2406   my $debug = !$opt{'quiet'} || $DEBUG;
2407   my $hascritical = 0;
2408
2409   warn "token_check called with opts\n".Dumper(\%opt) if $debug;
2410
2411   # force some explicitness when invoking this method
2412   die "token_check must run with queue flag if run with daily flag"
2413     if $opt{'daily'} && !$opt{'queue'};
2414
2415   my $conf = FS::Conf->new;
2416
2417   my $log = FS::Log->new('FS::cust_main::Billing_Realtime::token_check');
2418
2419   my $cache = {}; #cache for module info
2420
2421   # look for a gateway that can and can't tokenize
2422   my $require_tokenized = 1;
2423   my $someone_tokenizing = 0;
2424   foreach my $gateway (
2425     FS::payment_gateway->all_gateways(
2426       'method'  => 'CC',
2427       'conf'    => $conf,
2428       'nofatal' => 1,
2429     )
2430   ) {
2431     if (!$gateway) {
2432       # no default gateway, no promise to tokenize
2433       # can just load other gateways as-needeed below
2434       $require_tokenized = 0;
2435       last if $someone_tokenizing;
2436       next;
2437     }
2438     my $info = _token_check_gateway_info($cache,$gateway);
2439     die $info unless ref($info); # means it's an error message
2440     if ($info->{'can_tokenize'}) {
2441       $someone_tokenizing = 1;
2442     } else {
2443       # a configured gateway can't tokenize, that's all we need to know right now
2444       # can just load other gateways as-needeed below
2445       $require_tokenized = 0;
2446       last if $someone_tokenizing;
2447     }
2448   }
2449
2450   unless ($someone_tokenizing) { #no need to check, if no one can tokenize
2451     warn "no gateways tokenize\n" if $debug;
2452     return;
2453   }
2454
2455   warn "REQUIRE TOKENIZED" if $require_tokenized && $debug;
2456
2457   # upgrade does not call this with autocommit turned on,
2458   # and autocommit will be ignored if opt queue is set,
2459   # but might as well be thorough...
2460   my $oldAutoCommit = $FS::UID::AutoCommit;
2461   local $FS::UID::AutoCommit = 0;
2462   my $dbh = dbh;
2463
2464   # for retrieving data in chunks
2465   my $step = 500;
2466   my $offset = 0;
2467
2468   ### Tokenize cust_payby
2469
2470   my @recnums;
2471
2472 CUSTLOOP:
2473   while (my $custnum = _token_check_next_recnum($dbh,'cust_main',$step,\$offset,\@recnums)) {
2474     my $cust_main = FS::cust_main->by_key($custnum);
2475     my $payment_gateway;
2476     foreach my $cust_payby ($cust_main->cust_payby('CARD','DCRD')) {
2477
2478       # see if it's already tokenized
2479       if ($cust_payby->tokenized) {
2480         warn "cust_payby ".$cust_payby->get($cust_payby->primary_key)." already tokenized" if $debug;
2481         next;
2482       }
2483
2484       if ($require_tokenized && $opt{'daily'}) {
2485         $log->info("Untokenized card number detected in cust_payby ".$cust_payby->custpaybynum. '; tokenizing');
2486         $dbh->commit or die $dbh->errstr; # commit log message
2487       }
2488
2489       # only load gateway if we need to, and only need to load it once
2490       $payment_gateway ||= $cust_main->_payment_gateway({
2491         'method'  => 'CC',
2492         'conf'    => $conf,
2493         'nofatal' => 1, # handle lack of gateway smoothly below
2494       });
2495       unless ($payment_gateway) {
2496         # no reason to have untokenized card numbers saved if no gateway,
2497         #   but only a problem if we expected everyone to tokenize card numbers
2498         unless ($require_tokenized) {
2499           warn "Skipping cust_payby for cust_main ".$cust_main->custnum.", no payment gateway" if $debug;
2500           next CUSTLOOP; # can skip rest of customer
2501         }
2502         my $error = "No gateway found for custnum ".$cust_main->custnum;
2503         if ($opt{'queue'}) {
2504           $hascritical = 1;
2505           $log->critical($error);
2506           $dbh->commit or die $dbh->errstr; # commit error message
2507           next; # not next CUSTLOOP, want to record error for every cust_payby
2508         }
2509         $dbh->rollback if $oldAutoCommit;
2510         die $error;
2511       }
2512
2513       my $info = _token_check_gateway_info($cache,$payment_gateway);
2514       unless (ref($info)) {
2515         # only throws error if Business::OnlinePayment won't load,
2516         #   which is just cause to abort this whole process, even if queue
2517         $dbh->rollback if $oldAutoCommit;
2518         die $info; # error message
2519       }
2520       # no fail here--a configured gateway can't tokenize, so be it
2521       unless ($info->{'can_tokenize'}) {
2522         warn "Skipping ".$cust_main->custnum." cannot tokenize" if $debug;
2523         next;
2524       }
2525
2526       # time to tokenize
2527       $cust_payby = $cust_payby->select_for_update;
2528       my %tokenopts = (
2529         'payment_gateway' => $payment_gateway,
2530         'cust_payby'      => $cust_payby,
2531       );
2532       my $error = $cust_main->realtime_tokenize(\%tokenopts);
2533       if ($cust_payby->tokenized) { # implies no error
2534         $error = $cust_payby->replace;
2535       } else {
2536         $error ||= 'Unknown error';
2537       }
2538       if ($error) {
2539         $error = "Error tokenizing cust_payby ".$cust_payby->custpaybynum.": ".$error;
2540         if ($opt{'queue'}) {
2541           $hascritical = 1;
2542           $log->critical($error);
2543           $dbh->commit or die $dbh->errstr; # commit log message, release mutex
2544           next; # not next CUSTLOOP, want to record error for every cust_payby
2545         }
2546         $dbh->rollback if $oldAutoCommit;
2547         die $error;
2548       }
2549       $dbh->commit or die $dbh->errstr if $opt{'queue'}; # release mutex
2550       warn "TOKENIZED cust_payby ".$cust_payby->get($cust_payby->primary_key) if $debug;
2551     }
2552     warn "cust_payby upgraded for custnum ".$cust_main->custnum if $debug;
2553
2554   }
2555
2556   ### Tokenize/mask transaction tables
2557
2558   # allow tokenization of closed cust_pay/cust_refund records
2559   local $FS::payinfo_Mixin::allow_closed_replace = 1;
2560
2561   # grep assistance:
2562   #   $cust_pay_pending->replace, $cust_pay->replace, $cust_pay_void->replace, $cust_refund->replace all run here
2563   foreach my $table ( qw(cust_pay_pending cust_pay cust_pay_void cust_refund) ) {
2564     warn "Checking $table" if $debug;
2565
2566     # FS::Cursor does not seem to work over multiple commits (gives cursor not found errors)
2567     # loading only record ids, then loading individual records one at a time
2568     my $tclass = 'FS::'.$table;
2569     $offset = 0;
2570     @recnums = ();
2571
2572     while (my $recnum = _token_check_next_recnum($dbh,$table,$step,\$offset,\@recnums)) {
2573       my $record = $tclass->by_key($recnum);
2574       unless ($record->payby eq 'CARD') {
2575         warn "Skipping non-card record for $table ".$record->get($record->primary_key) if $debug;
2576         next;
2577       }
2578       if (FS::cust_main::Billing_Realtime->tokenized($record->payinfo)) {
2579         warn "Skipping tokenized record for $table ".$record->get($record->primary_key) if $debug;
2580         next;
2581       }
2582       if (!$record->payinfo) { #shouldn't happen, but at least it's not a card number
2583         warn "Skipping blank payinfo for $table ".$record->get($record->primary_key) if $debug;
2584         next;
2585       }
2586       if ($record->payinfo =~ /N\/A/) { # ??? Not sure why we do this, but it's not a card number
2587         warn "Skipping NA payinfo for $table ".$record->get($record->primary_key) if $debug;
2588         next;
2589       }
2590
2591       if ($require_tokenized && $opt{'daily'}) {
2592         $log->info("Untokenized card number detected in $table ".$record->get($record->primary_key). ';tokenizing');
2593         $dbh->commit or die $dbh->errstr; # commit log message
2594       }
2595
2596       my $cust_main = $record->cust_main;
2597       if (!$cust_main) {
2598         # might happen for cust_pay_pending from failed verify records,
2599         #   in which case we attempt tokenization without cust_main
2600         # everything else should absolutely have a cust_main
2601         if ($table eq 'cust_pay_pending' and !$record->custnum ) {
2602           # override the usual safety check and allow the record to be
2603           # updated even without a custnum.
2604           $record->set('custnum_pending', 1);
2605         } else {
2606           my $error = "Could not load cust_main for $table ".$record->get($record->primary_key);
2607           if ($opt{'queue'}) {
2608             $hascritical = 1;
2609             $log->critical($error);
2610             $dbh->commit or die $dbh->errstr; # commit log message
2611             next;
2612           }
2613           $dbh->rollback if $oldAutoCommit;
2614           die $error;
2615         }
2616       }
2617
2618       my $gateway;
2619
2620       # use the gatewaynum specified by the record if possible
2621       $gateway = FS::payment_gateway->by_key_with_namespace(
2622         'gatewaynum' => $record->gatewaynum,
2623       ) if $record->gateway;
2624
2625       # otherwise use the cust agent gateway if possible (which realtime_refund_bop would do)
2626       # otherwise just use default gateway
2627       unless ($gateway) {
2628
2629         $gateway = $cust_main 
2630                  ? $cust_main->agent->payment_gateway
2631                  : FS::payment_gateway->default_gateway;
2632
2633         # check for processor mismatch
2634         unless ($table eq 'cust_pay_pending') { # has no processor table
2635           if (my $processor = $record->processor) {
2636
2637             my $conf_processor = $gateway->gateway_module;
2638             my %bop_options = $gateway->gatewaynum
2639                             ? $gateway->options
2640                             : @{ $gateway->get('options') };
2641
2642             # this is the same standard used by realtime_refund_bop
2643             unless (
2644               ($processor eq $conf_processor) ||
2645               (($conf_processor eq 'CardFortress') && ($processor eq $bop_options{'gateway'}))
2646             ) {
2647
2648               # processors don't match, so refund already cannot be run on this object,
2649               # regardless of what we do now...
2650               # but unless we gotta tokenize everything, just leave well enough alone
2651               unless ($require_tokenized) {
2652                 warn "Skipping mismatched processor for $table ".$record->get($record->primary_key) if $debug;
2653                 next;
2654               }
2655               ### no error--we'll tokenize using the new gateway, just to remove stored payinfo,
2656               ### because refunds are already impossible for this record, anyway
2657
2658             } # end processor mismatch
2659
2660           } # end record has processor
2661         } # end not cust_pay_pending
2662
2663       }
2664
2665       # means no default gateway, no promise to tokenize, can skip
2666       unless ($gateway) {
2667         warn "Skipping missing gateway for $table ".$record->get($record->primary_key) if $debug;
2668         next;
2669       }
2670
2671       my $info = _token_check_gateway_info($cache,$gateway);
2672       unless (ref($info)) {
2673         # only throws error if Business::OnlinePayment won't load,
2674         #   which is just cause to abort this whole process, even if queue
2675         $dbh->rollback if $oldAutoCommit;
2676         die $info; # error message
2677       }
2678
2679       # a configured gateway can't tokenize, move along
2680       unless ($info->{'can_tokenize'}) {
2681         warn "Skipping, cannot tokenize $table ".$record->get($record->primary_key) if $debug;
2682         next;
2683       }
2684
2685       warn "ATTEMPTING GATEWAY-ONLY TOKENIZE" if $debug && !$cust_main;
2686
2687       # if we got this far, time to mutex
2688       $record->select_for_update;
2689
2690       # no clear record of name/address/etc used for transaction,
2691       # but will load name/phone/id from customer if run as an object method,
2692       # so we try that if we can
2693       my %tokenopts = (
2694         'payment_gateway' => $gateway,
2695         'method'          => 'CC',
2696         'payinfo'         => $record->payinfo,
2697         'paydate'         => $record->paydate,
2698       );
2699       my $error = $cust_main
2700                 ? $cust_main->realtime_tokenize(\%tokenopts)
2701                 : FS::cust_main::Billing_Realtime->realtime_tokenize(\%tokenopts);
2702       if (FS::cust_main::Billing_Realtime->tokenized($tokenopts{'payinfo'})) { # implies no error
2703         $record->payinfo($tokenopts{'payinfo'});
2704         $error = $record->replace;
2705       } else {
2706         $error ||= 'Unknown error';
2707       }
2708       if ($error) {
2709         $error = "Error tokenizing $table ".$record->get($record->primary_key).": ".$error;
2710         if ($opt{'queue'}) {
2711           $hascritical = 1;
2712           $log->critical($error);
2713           $dbh->commit or die $dbh->errstr; # commit log message, release mutex
2714           next;
2715         }
2716         $dbh->rollback if $oldAutoCommit;
2717         die $error;
2718       }
2719       $dbh->commit or die $dbh->errstr if $opt{'queue'}; # release mutex
2720       warn "TOKENIZED $table ".$record->get($record->primary_key) if $debug;
2721
2722     } # end record loop
2723   } # end table loop
2724
2725   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
2726
2727   return $hascritical ? 'Critical errors occurred on some records, see system log' : '';
2728 }
2729
2730 # not a method!
2731 sub _token_check_next_recnum {
2732   my ($dbh,$table,$step,$offset,$recnums) = @_;
2733   my $recnum = shift @$recnums;
2734   return $recnum if $recnum;
2735   my $tclass = 'FS::'.$table;
2736   my $sth = $dbh->prepare(
2737     'SELECT '.$tclass->primary_key.
2738     ' FROM '.$table.
2739     " WHERE ( is_tokenized IS NULL OR is_tokenized = '' ) ".
2740     ' ORDER BY '.$tclass->primary_key.
2741     ' LIMIT '.$step.
2742     ' OFFSET '.$$offset
2743   ) or die $dbh->errstr;
2744   $sth->execute() or die $sth->errstr;
2745   my @recnums;
2746   while (my $rec = $sth->fetchrow_hashref) {
2747     push @$recnums, $rec->{$tclass->primary_key};
2748   }
2749   $sth->finish();
2750   $$offset += $step;
2751   return shift @$recnums;
2752 }
2753
2754 # not a method!
2755 sub _token_check_gateway_info {
2756   my ($cache,$payment_gateway) = @_;
2757
2758   return $cache->{$payment_gateway->gateway_module}
2759     if $cache->{$payment_gateway->gateway_module};
2760
2761   my $info = {};
2762   $cache->{$payment_gateway->gateway_module} = $info;
2763
2764   my $namespace = $payment_gateway->gateway_namespace;
2765   return $info unless $namespace eq 'Business::OnlinePayment';
2766   $info->{'is_bop'} = 1;
2767
2768   # only need to load this once,
2769   # don't want to load if nothing is_bop
2770   unless ($cache->{'Business::OnlinePayment'}) {
2771     eval "use $namespace";  
2772     return "Error initializing Business:OnlinePayment: ".$@ if $@;
2773     $cache->{'Business::OnlinePayment'} = 1;
2774   }
2775
2776   my $transaction = new $namespace( $payment_gateway->gateway_module,
2777                                     _bop_options({ 'payment_gateway' => $payment_gateway }),
2778                                   );
2779
2780   return $info unless $transaction->can('info');
2781   $info->{'can_info'} = 1;
2782
2783   my %supported_actions = $transaction->info('supported_actions');
2784   $info->{'can_tokenize'} = 1
2785     if $supported_actions{'CC'}
2786       && grep /^Tokenize$/, @{$supported_actions{'CC'}};
2787
2788   # not using this any more, but for future reference...
2789   $info->{'void_requires_card'} = 1
2790     if $transaction->info('CC_void_requires_card');
2791
2792   return $info;
2793 }
2794
2795 =back
2796
2797 =head1 BUGS
2798
2799 =head1 SEE ALSO
2800
2801 L<FS::cust_main>, L<FS::cust_main::Billing>
2802
2803 =cut
2804
2805 1;