we're at now now
[Business-OnlinePayment.git] / OnlinePayment.pm
1 package Business::OnlinePayment;
2
3 use strict;
4 use vars qw($VERSION %_info_handler);
5 use Carp;
6
7 require 5.005;
8
9 $VERSION = '3.05_01';
10 $VERSION = eval $VERSION; # modperlstyle: convert the string into a number
11
12 # Remember subclasses we have "wrapped" submit() with _pre_submit()
13 my %Presubmit_Added = ();
14
15 my @methods = qw(
16     authorization
17     order_number
18     error_message
19     failure_status
20     fraud_detect
21     is_success
22     partial_auth_amount
23     maximum_risk
24     path
25     port
26     require_avs
27     result_code
28     server
29     server_response
30     test_transaction
31     transaction_type
32     fraud_score
33     fraud_transaction_id
34     response_code
35     response_header
36     response_page
37     avs_code
38     cvv2_response
39     txn_date
40 );
41
42 __PACKAGE__->build_subs(@methods);
43
44 #fallback
45 sub _info {
46   my $class = shift;
47   ( my $gw = $class ) =~ s/^Business::OnlinePayment:://;
48   {
49     'info_compat'    => '0.00',
50     'gateway_name'   => $gw,
51     'module_notes'   => "Module does not yet provide info.",
52   };
53 }
54
55 #allow classes to declare info in a flexible way, but return normalized info
56 %_info_handler = (
57   'supported_types'   => sub {
58     my( $class, $v ) = @_;
59     my $types = ref($v) ? $v : defined($v) ? [ $v ] : [];
60     $types = { map { $_=>1 } @$types } if ref($types) eq 'ARRAY';
61     $types;
62   },
63   'supported_actions' => sub {
64     my( $class, $v ) = @_;
65     return %$v if ref($v) eq 'HASH';
66     $v = [ $v ] unless ref($v);
67     my $types = $class->info('supported_types') || {};
68     ( map { $_ => $v } keys %$types );
69   },
70 );
71
72 sub info {
73   my $class = shift; #class or object
74   my $info = $class->_info;
75   if ( @_ ) {
76     my $key = shift;
77     exists($_info_handler{$key})
78       ? &{ $_info_handler{$key} }( $class, $info->{$key} )
79       : $info->{$key};
80   } else {
81     wantarray ? ( keys %$info ) : [ keys %$info ];
82   }
83 }
84
85 sub new {
86     my($class,$processor,%data) = @_;
87
88     croak("unspecified processor") unless $processor;
89
90     my $subclass = "${class}::$processor";
91     eval "use $subclass";
92     croak("unknown processor $processor ($@)") if $@;
93
94     my $self = bless {processor => $processor}, $subclass;
95
96     if($self->can("set_defaults")) {
97         $self->set_defaults(%data);
98     }
99
100     foreach(keys %data) {
101         my $key = lc($_);
102         my $value = $data{$_};
103         $key =~ s/^\-+//;
104         $self->build_subs($key);
105         $self->$key($value);
106     }
107
108     # "wrap" submit with _pre_submit only once
109     unless ( $Presubmit_Added{$subclass} ) {
110         my $real_submit = $subclass->can('submit');
111
112         no warnings 'redefine';
113         no strict 'refs';
114
115         *{"${subclass}::submit"} = sub {
116             my $self = shift;
117             return unless $self->_pre_submit(@_);
118             return $real_submit->($self, @_);
119         }
120     }
121
122     return $self;
123 }
124
125 sub _risk_detect {
126     my ($self, $risk_transaction) = @_;
127
128     my %parent_content = $self->content();
129     $parent_content{action} = 'Fraud Detect';
130     $risk_transaction->content( %parent_content );
131     $risk_transaction->submit();
132     if ($risk_transaction->is_success()) {
133          $self->fraud_score( $risk_transaction->fraud_score );
134          $self->fraud_transaction_id( $risk_transaction->fraud_transaction_id );
135         if ( $risk_transaction->fraud_score <= $self->maximum_fraud_score()) {
136             return 1;
137         } else {
138             $self->error_message('Excessive risk from risk management');
139         }
140     } else {
141         $self->error_message('Error in risk detection stage: ' .  $risk_transaction->error_message);
142     }
143     $self->is_success(0);
144     return 0;
145 }
146
147 my @Fraud_Class_Path = qw(Business::OnlinePayment Business::FraudDetect);
148
149 sub _pre_submit {
150     my ($self) = @_;
151     my $fraud_detection = $self->fraud_detect();
152
153     # early return if user does not want optional risk mgt
154     return 1 unless $fraud_detection;
155
156     # Search for an appropriate FD module
157     foreach my $fraud_class ( @Fraud_Class_Path ) {
158         my $subclass = $fraud_class . "::" . $fraud_detection;
159         eval "use $subclass ()";
160         if ($@) {
161             croak("error loading fraud_detection module ($@)")
162               unless ( $@ =~ m/^Can\'t locate/ );
163         } else {
164             my $risk_tx = bless( { processor => $fraud_detection }, $subclass );
165             if ($risk_tx->can('set_defaults')) {
166                 $risk_tx->set_defaults();
167             }
168             $risk_tx->_glean_parameters_from_parent($self);
169             return $self->_risk_detect($risk_tx);
170         }
171     }
172     croak("Unable to locate fraud_detection module $fraud_detection"
173                 . " in \@INC under Fraud_Class_Path (\@Fraud_Class_Path"
174                 . " contains: @Fraud_Class_Path) (\@INC contains: @INC)");
175 }
176
177 sub content {
178     my($self,%params) = @_;
179
180     if(%params) {
181         if($params{'type'}) { $self->transaction_type($params{'type'}); }
182         %{$self->{'_content'}} = %params;
183     }
184     return exists $self->{'_content'} ? %{$self->{'_content'}} : ();
185 }
186
187 sub required_fields {
188     my($self,@fields) = @_;
189
190     my @missing;
191     my %content = $self->content();
192     foreach(@fields) {
193         push(@missing, $_) unless exists $content{$_};
194     }
195
196     croak("missing required field(s): " . join(", ", @missing) . "\n")
197           if(@missing);
198 }
199
200 sub get_fields {
201     my($self, @fields) = @_;
202
203     my %content = $self->content();
204
205     #my %new = ();
206     #foreach(@fields) { $new{$_} = $content{$_}; }
207     #return %new;
208     map { $_ => $content{$_} } grep defined $content{$_}, @fields;
209 }
210
211 sub remap_fields {
212     my($self,%map) = @_;
213
214     my %content = $self->content();
215     foreach( keys %map ) {
216         $content{$map{$_}} = $content{$_};
217     }
218     $self->content(%content);
219 }
220
221 sub submit {
222     my($self) = @_;
223
224     croak("Processor subclass did not override submit function");
225 }
226
227 sub dump_contents {
228     my($self) = @_;
229
230     my %content = $self->content();
231     my $dump = "";
232     foreach(sort keys %content) {
233         $dump .= "$_ = $content{$_}\n";
234     }
235     return $dump;
236 }
237
238 # didnt use AUTOLOAD because Net::SSLeay::AUTOLOAD passes right to
239 # AutoLoader::AUTOLOAD, instead of passing up the chain
240 sub build_subs {
241     my $self = shift;
242
243     foreach(@_) {
244         next if($self->can($_));
245         eval "sub $_ { my \$self = shift; if(\@_) { \$self->{$_} = shift; } return \$self->{$_}; }";
246     }
247 }
248
249 #helper method
250
251 sub silly_bool {
252   my( $self, $value ) = @_;
253   return 1 if $value =~ /^[yt]/i;
254   return 0 if $value =~ /^[fn]/i;
255   #return 1 if $value == 1;
256   #return 0 if $value == 0;
257   $value; #die??
258 }
259
260 1;
261
262 __END__
263
264 =head1 NAME
265
266 Business::OnlinePayment - Perl extension for online payment processing
267
268 =head1 SYNOPSIS
269
270   use Business::OnlinePayment;
271   
272   my $transaction = new Business::OnlinePayment($processor, %processor_info);
273   $transaction->content(
274                         type        => 'Visa',
275                         amount      => '49.95',
276                         card_number => '1234123412341238',
277                         expiration  => '06/15',
278                         name        => 'John Q Doe',
279                        );
280
281   eval { $transaction->submit(); };
282
283   if ( $@ ) {
284
285     print "$processor error: $@\n";
286
287   } else {
288   
289     if ( $transaction->is_success() ) {
290       print "Card processed successfully: ". $transaction->authorization()."\n";
291     } else {
292       print "Card was rejected: ". $transaction->error_message(). "\n";
293     }
294
295   }
296
297 =head1 DESCRIPTION
298
299 Business::OnlinePayment is a generic module for processing payments
300 through online credit card processors, electronic cash systems, etc.
301
302 =head1 CONSTRUCTOR
303
304 =head2 new($processor, %processor_options)
305
306 Create a new Business::OnlinePayment object, $processor is required,
307 and defines the online processor to use.  If necessary, processor
308 options can be specified, currently supported options are 'Server',
309 'Port', and 'Path', which specify how to find the online processor
310 (https://server:port/path), but individual processor modules should
311 supply reasonable defaults for this information, override the defaults
312 only if absolutely necessary (especially path), as the processor
313 module was probably written with a specific target script in mind.
314
315 =head1 TRANSACTION SETUP METHODS
316
317 =head2 content(%content)
318
319 The information necessary for the transaction, this tends to vary a
320 little depending on the processor, so we have chosen to use a system
321 which defines specific fields in the frontend which get mapped to the
322 correct fields in the backend.  The currently defined fields are:
323
324 =head3 PROCESSOR FIELDS
325
326 =over 4
327
328 =item login
329
330 Your login name to use for authentication to the online processor.
331
332 =item password
333
334 Your password to use for authentication to the online processor.
335
336 =back
337
338 =head3 REQUIRED TRANSACTION FIELDS
339
340 =over 4
341
342 =item type
343
344 Transaction type, supported types are: CC (credit card), ECHECK
345 (electronic check) and LEC (phone bill billing).  Deprecated types
346 are: Visa, MasterCard, American Express, Discover, Check.  Not all
347 processors support all transaction types.
348
349 =item action
350
351 What action being taken by this transaction. Currently available are:
352
353 =over 8
354
355 =item Normal Authorization
356
357 =item Authorization Only
358
359 =item Post Authorization
360
361 =item Reverse Authorization
362
363 =item Void
364
365 =item Credit
366
367 =item Tokenize
368
369 =item Recurring Authorization
370
371 =item Modify Recurring Authorization
372
373 =item Cancel Recurring Authorization
374
375 =back
376
377 =item amount
378
379 The amount of the transaction.  No dollar signs or currency identifiers,
380 just a whole or floating point number (i.e. 26, 26.1 or 26.13).
381
382 =back
383
384 =head3 OPTIONAL TRANSACTION FIELDS
385
386 =over 4
387
388 =item partial_auth
389
390 If you are prepared to handle partial authorizations
391 (see L<partial_auth_amount()|/"partial_auth_amount()">
392  in L<TRANSACTION RESULT FIELDS|/"TRANSACTION RESULT FIELDS">),
393 pass a true value in this field to enable them.
394
395 If this flag is not set, a partial authorization will be immediately reversed
396 or voided.
397
398 =item description
399
400 A description of the transaction (used by some processors to send
401 information to the client, normally not a required field).
402
403 =item invoice_number
404
405 An invoice number, for your use and not normally required, many
406 processors require this field to be a numeric only field.
407
408 =item po_number
409
410 Purchase order number (normally not required).
411
412 =item tax
413
414 Tax amount (portion of amount field, not added to it).
415
416 =item freight
417
418 Freight amount (portion of amount field, not added to it).
419
420 =item duty
421
422 Duty amount (portion of amount field, not added to it).
423
424 =item tax_exempt
425
426 Tax exempt flag (i.e. TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0).
427
428 =item currency
429
430 Currency, specified as an ISO 4217 three-letter code, such as USD, CAD, EUR,
431 AUD, DKK, GBP, JPY, NZD, etc.
432
433 =back
434
435 =head3 CUSTOMER INFO FIELDS
436
437 =over 4
438
439 =item customer_id
440
441 A customer identifier, again not normally required.
442
443 =item name
444
445 The customer's name, your processor may not require this.
446
447 =item first_name
448
449 =item last_name
450
451 The customer's first and last name as separate fields.
452
453 =item company
454
455 The customer's company name, not normally required.
456
457 =item address
458
459 The customer's address (your processor may not require this unless you
460 are requiring AVS Verification).
461
462 =item city
463
464 The customer's city (your processor may not require this unless you
465 are requiring AVS Verification).
466
467 =item state
468
469 The customer's state (your processor may not require this unless you
470 are requiring AVS Verification).
471
472 =item zip
473
474 The customer's zip code (your processor may not require this unless
475 you are requiring AVS Verification).
476
477 =item country
478
479 Customer's country.
480
481 =item ship_first_name
482
483 =item ship_last_name
484
485 =item ship_company
486
487 =item ship_address
488
489 =item ship_city
490
491 =item ship_state
492
493 =item ship_zip
494
495 =item ship_country
496
497 These shipping address fields may be accepted by your processor.
498 Refer to the description for the corresponding non-ship field for
499 general information on each field.
500
501 =item phone
502
503 Customer's phone number.
504
505 =item fax
506
507 Customer's fax number.
508
509 =item email
510
511 Customer's email address.
512
513 =item customer_ip
514
515 IP Address from which the transaction originated.
516
517 =back
518
519 =head3 CREDIT CARD FIELDS
520
521 =over 4
522
523 =item card_number
524
525 Credit card number.
526
527 =item expiration
528
529 Credit card expiration, MM/YY.
530
531 =item cvv2
532
533 CVV2 number (also called CVC2 or CID) is a three- or four-digit
534 security code used to reduce credit card fraud.
535
536 =item card_token
537
538 If supported by your gateway, you can pass a card_token instead of a
539 card_number and expiration.
540
541 =cut
542
543 #=item card_response
544 #
545 #Some card_token schemes implement a challenge/response handshake.  In those
546 #cases, this field is used for the response.  In most cases the handshake
547 #it taken care of by the gateway module.
548
549 =item track1
550
551 Track 1 on the magnetic stripe (Card present only)
552
553 =item track2
554
555 Track 2 on the magnetic stripe (Card present only)
556
557 =item recurring_billing
558
559 Recurring billing flag
560
561 =back
562
563 =head3 ELECTRONIC CHECK FIELDS
564
565 =over 4
566
567 =item account_number
568
569 Bank account number
570
571 =item routing_code
572
573 Bank's routing code
574
575 =item account_type
576
577 Account type.  Can be (case-insensitive): B<Personal Checking>,
578 B<Personal Savings>, B<Business Checking> or B<Business Savings>.
579
580 =item account_name
581
582 Account holder's name.
583
584 =item bank_name
585
586 Bank name.
587
588 =item bank_city
589
590 Bank city.
591
592 =item bank_state
593
594 Bank state.
595
596 =item check_type
597
598 Check type.
599
600 =item customer_org
601
602 Customer organization type.
603
604 =item customer_ssn
605
606 Customer's social security number.
607
608 =item license_num
609
610 Customer's driver's license number.
611
612 =item license_dob
613
614 Customer's date of birth.
615
616 =back
617
618 =head3 FOLLOW-UP TRANSACTION FIELDS
619
620 These fields are used in follow-up transactions related to an original
621 transaction (Post Authorization, Reverse Authorization, Void, Credit).
622
623 =over 4
624
625 =item authorization
626
627 =item order_number
628
629 =item txn_date
630
631 =back
632
633 =head3 RECURRING BILLING FIELDS
634
635 =over 4
636
637 =item interval 
638
639 Interval expresses the amount of time between billings: digits, whitespace
640 and units (currently "days" or "months" in either singular or plural form).
641
642 =item start
643
644 The date of the first transaction (used for processors which allow delayed
645 start) expressed as YYYY-MM-DD.
646
647 =item periods
648
649 The number of cycles of interval length for which billing should occur 
650 (inclusive of 'trial periods' if the processor supports recurring billing
651 at more than one rate)
652
653 =back
654
655 =head2 test_transaction()
656
657 Most processors provide a test mode, where submitted transactions will
658 not actually be charged or added to your batch, calling this function
659 with a true argument will turn that mode on if the processor supports
660 it, or generate a fatal error if the processor does not support a test
661 mode (which is probably better than accidentally making real charges).
662
663 =head2 require_avs()
664
665 Providing a true argument to this module will turn on address
666 verification (if the processor supports it).
667
668 =head1 TRANSACTION SUBMISSION METHOD
669
670 =head2 submit()
671
672 Submit the transaction to the processor for completion.
673
674 If there is a gateway communication error or other "meta" , the submit method
675 will throw a fatal exception.  You can catch this with eval {} if you would
676 like to treat gateway co
677
678 =head1 TRANSACTION RESULT METHODS
679
680 =head2 is_success()
681
682 Returns true if the transaction was approved by the gateway, false if 
683 it was submitted but not approved, or undef if it has not been 
684 submitted yet.
685
686 =head2 partial_auth_amount()
687
688 If this transaction was a partial authorization (i.e. successful, but less than
689 the requested amount was processed), then the amount processed is returned in
690 this field.
691
692 (When is_success is true but this field is empty or 0, that indicates a normal
693 full authorization for the entire requested amount.)
694
695 =head2 error_message()
696
697 If the transaction has been submitted but was not accepted, this
698 function will return the provided error message (if any) that the
699 processor returned.
700
701 =head2 failure_status()
702
703 If the transaction failed, it can optionally return a specific failure
704 status (normalized, not gateway-specific).  Currently defined statuses
705 are: "expired", "nsf" (non-sufficient funds), "stolen", "pickup",
706 "blacklisted" and "declined" (card/transaction declines only, not
707 other errors).
708
709 Note that not all processor modules support this, and that if supported,
710 it may not be set for all declines.
711
712 =head2 authorization()
713
714 If the transaction has been submitted and accepted, this function will
715 provide you with the authorization code that the processor returned.
716 Store this if you would like to run inquiries or refunds on the transaction
717 later.
718
719 =head2 order_number()
720
721 The unique order number for the transaction generated by the gateway.  Store
722 this if you would like to run inquiries or refunds on the transaction later.
723
724 =head2 card_token()
725
726 If supported by your gateway, a card_token can be used in a subsequent
727 transaction to refer to a card number.
728
729 =head2 txn_date()
730
731 Transaction date, as returned by the gateway.  Required by some gateways
732 for follow-up transactions.  Store this if you would like to run inquiries or
733 refunds on the transaction later.
734
735 =head2 fraud_score()
736
737 Retrieve or change the fraud score from any Business::FraudDetect plugin
738
739 =head2 fraud_transaction_id()
740
741 Retrieve or change the transaction id from any Business::FraudDetect plugin
742
743 =head2 response_code()
744
745 =head2 response_headers()
746
747 =head2 response_page()
748
749 These three fields are set by some processors (especially those which use
750 HTTPS) when the transaction fails at the communication level rather than
751 as a transaction.
752
753 response_code is the HTTP response code and message, i.e.
754 '500 Internal Server Error'.
755
756 response_headers is a hash reference of the response headers
757
758 response_page is the raw content.
759
760 =head2 result_code()
761
762 Returns the precise result code that the processor returned, these are
763 normally one letter codes that don't mean much unless you understand
764 the protocol they speak, you probably don't need this, but it's there
765 just in case.
766
767 =head2 avs_code()
768
769 =head2 cvv2_response()
770
771 =head1 MISCELLANEOUS INTERNAL METHODS
772
773 =head2 transaction_type()
774
775 Retrieve the transaction type (the 'type' argument to contents()).
776 Generally only used internally, but provided in case it is useful.
777
778 =head2 server()
779
780 Retrieve or change the processor submission server address (CHANGE AT
781 YOUR OWN RISK).
782
783 =head2 port()
784
785 Retrieve or change the processor submission port (CHANGE AT YOUR OWN
786 RISK).
787
788 =head2 path()
789
790 Retrieve or change the processor submission path (CHANGE AT YOUR OWN
791 RISK).
792
793 =head1 HELPER METHODS FOR GATEWAY MODULE AUTHORS
794
795 =head2 build_subs( @sub_names )
796
797 Build setter/getter subroutines for new return values.
798
799 =head2 get_fields( @fields )
800
801 Get the named fields if they are defined.
802
803 =head2 remap_fields( %map )
804
805 Remap field content (and stuff it back into content).
806
807 =head2 required_fields( @fields )
808
809 Croaks if any of the required fields are not present.
810
811 =head2 dump_contents
812
813 =head2 silly_bool( $value )
814
815 Returns 1 if the value starts with y, Y, t or T.
816 Returns 0 if the value starts with n, N, f or F.
817 Otherwise returns the value itself.
818
819 Use this for handling boolean content like tax_exempt.
820
821 =head1 AUTHORS
822
823 (v2 series)
824
825 Jason Kohles, email@jasonkohles.com
826
827 (v3 rewrite)
828
829 Ivan Kohler <ivan-business-onlinepayment@420.am>
830
831 Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
832
833 =head1 COPYRIGHT
834
835 Copyright (c) 1999-2004 Jason Kohles
836 Copyright (c) 2004 Ivan Kohler
837 Copyright (c) 2007-2016 Freeside Internet Services, Inc.
838
839 All rights reserved.
840
841 This program is free software; you can redistribute it and/or modify it under
842 the same terms as Perl itself.
843
844 =head1 HOMEPAGE
845
846 Homepage:  http://perl.business/onlinepayment
847
848 Development:  http://perl.business/onlinepayment/ng.html
849
850 =head1 MAILING LIST
851
852 Please direct current development questions, patches, etc. to the mailing list:
853 http://420.am/cgi-bin/mailman/listinfo/bop-devel/
854
855 =head1 REPOSITORY
856
857 The code is available from our public git repository:
858
859   git clone git://git.freeside.biz/Business-OnlinePayment.git
860
861 Or on the web:
862
863   http://freeside.biz/gitweb/?p=Business-OnlinePayment.git
864   Or:
865   http://freeside.biz/gitlist/Business-OnlinePayment.git
866
867 Many (but by no means all!) processor plugins are also available in the same
868 repository, see:
869
870   http://freeside.biz/gitweb/
871   Or:
872   http://freeside.biz/gitlist/
873
874 =head1 DISCLAIMER
875
876 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
877 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
878 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
879
880 =head1 SEE ALSO
881
882 http://perl.business/onlinepayment
883
884 For verification of credit card checksums, see L<Business::CreditCard>.
885
886 =cut