1 package Business::OnlinePayment;
4 use vars qw($VERSION %_info_handler);
10 $VERSION = eval $VERSION; # modperlstyle: convert the string into a number
12 # Remember subclasses we have "wrapped" submit() with _pre_submit()
13 my %Presubmit_Added = ();
41 __PACKAGE__->build_subs(@methods);
46 ( my $gw = $class ) =~ s/^Business::OnlinePayment:://;
48 'info_compat' => '0.00',
49 'gateway_name' => $gw,
50 'module_notes' => "Module does not yet provide info.",
54 #allow classes to declare info in a flexible way, but return normalized info
56 'supported_types' => sub {
57 my( $class, $v ) = @_;
58 my $types = ref($v) ? $v : defined($v) ? [ $v ] : [];
59 $types = { map { $_=>1 } @$types } if ref($types) eq 'ARRAY';
62 'supported_actions' => sub {
63 my( $class, $v ) = @_;
64 return %$v if ref($v) eq 'HASH';
65 $v = [ $v ] unless ref($v);
66 my $types = $class->info('supported_types') || {};
67 ( map { $_ => $v } keys %$types );
72 my $class = shift; #class or object
73 my $info = $class->_info;
76 exists($_info_handler{$key})
77 ? &{ $_info_handler{$key} }( $class, $info->{$key} )
80 wantarray ? ( keys %$info ) : [ keys %$info ];
85 my($class,$processor,%data) = @_;
87 croak("unspecified processor") unless $processor;
89 my $subclass = "${class}::$processor";
91 croak("unknown processor $processor ($@)") if $@;
93 my $self = bless {processor => $processor}, $subclass;
95 if($self->can("set_defaults")) {
96 $self->set_defaults(%data);
101 my $value = $data{$_};
103 $self->build_subs($key);
107 # "wrap" submit with _pre_submit only once
108 unless ( $Presubmit_Added{$subclass} ) {
109 my $real_submit = $subclass->can('submit');
111 no warnings 'redefine';
114 *{"${subclass}::submit"} = sub {
116 return unless $self->_pre_submit(@_);
117 return $real_submit->($self, @_);
125 my ($self, $risk_transaction) = @_;
127 my %parent_content = $self->content();
128 $parent_content{action} = 'Fraud Detect';
129 $risk_transaction->content( %parent_content );
130 $risk_transaction->submit();
131 if ($risk_transaction->is_success()) {
132 $self->fraud_score( $risk_transaction->fraud_score );
133 $self->fraud_transaction_id( $risk_transaction->fraud_transaction_id );
134 if ( $risk_transaction->fraud_score <= $self->maximum_fraud_score()) {
137 $self->error_message('Excessive risk from risk management');
140 $self->error_message('Error in risk detection stage: ' . $risk_transaction->error_message);
142 $self->is_success(0);
146 my @Fraud_Class_Path = qw(Business::OnlinePayment Business::FraudDetect);
150 my $fraud_detection = $self->fraud_detect();
152 # early return if user does not want optional risk mgt
153 return 1 unless $fraud_detection;
155 # Search for an appropriate FD module
156 foreach my $fraud_class ( @Fraud_Class_Path ) {
157 my $subclass = $fraud_class . "::" . $fraud_detection;
158 eval "use $subclass ()";
160 croak("error loading fraud_detection module ($@)")
161 unless ( $@ =~ m/^Can\'t locate/ );
163 my $risk_tx = bless( { processor => $fraud_detection }, $subclass );
164 if ($risk_tx->can('set_defaults')) {
165 $risk_tx->set_defaults();
167 $risk_tx->_glean_parameters_from_parent($self);
168 return $self->_risk_detect($risk_tx);
171 croak("Unable to locate fraud_detection module $fraud_detection"
172 . " in \@INC under Fraud_Class_Path (\@Fraud_Class_Path"
173 . " contains: @Fraud_Class_Path) (\@INC contains: @INC)");
177 my($self,%params) = @_;
180 if($params{'type'}) { $self->transaction_type($params{'type'}); }
181 %{$self->{'_content'}} = %params;
183 return exists $self->{'_content'} ? %{$self->{'_content'}} : ();
186 sub required_fields {
187 my($self,@fields) = @_;
190 my %content = $self->content();
192 push(@missing, $_) unless exists $content{$_};
195 croak("missing required field(s): " . join(", ", @missing) . "\n")
200 my($self, @fields) = @_;
202 my %content = $self->content();
205 #foreach(@fields) { $new{$_} = $content{$_}; }
207 map { $_ => $content{$_} } grep defined $content{$_}, @fields;
213 my %content = $self->content();
214 foreach( keys %map ) {
215 $content{$map{$_}} = $content{$_};
217 $self->content(%content);
223 croak("Processor subclass did not override submit function");
229 my %content = $self->content();
231 foreach(sort keys %content) {
232 $dump .= "$_ = $content{$_}\n";
237 # didnt use AUTOLOAD because Net::SSLeay::AUTOLOAD passes right to
238 # AutoLoader::AUTOLOAD, instead of passing up the chain
243 next if($self->can($_));
244 eval "sub $_ { my \$self = shift; if(\@_) { \$self->{$_} = shift; } return \$self->{$_}; }";
251 my( $self, $value ) = @_;
252 return 1 if $value =~ /^[yt]/i;
253 return 0 if $value =~ /^[fn]/i;
254 #return 1 if $value == 1;
255 #return 0 if $value == 0;
265 Business::OnlinePayment - Perl extension for online payment processing
269 use Business::OnlinePayment;
271 my $transaction = new Business::OnlinePayment($processor, %processor_info);
272 $transaction->content(
275 card_number => '1234123412341238',
276 expiration => '06/15',
277 name => 'John Q Doe',
280 eval { $transaction->submit(); };
284 print "$processor error: $@\n";
288 if ( $transaction->is_success() ) {
289 print "Card processed successfully: ". $transaction->authorization()."\n";
291 print "Card was rejected: ". $transaction->error_message(). "\n";
298 Business::OnlinePayment is a generic module for processing payments
299 through online credit card processors, electronic cash systems, etc.
303 =head2 new($processor, %processor_options)
305 Create a new Business::OnlinePayment object, $processor is required,
306 and defines the online processor to use. If necessary, processor
307 options can be specified, currently supported options are 'Server',
308 'Port', and 'Path', which specify how to find the online processor
309 (https://server:port/path), but individual processor modules should
310 supply reasonable defaults for this information, override the defaults
311 only if absolutely necessary (especially path), as the processor
312 module was probably written with a specific target script in mind.
314 =head1 TRANSACTION SETUP METHODS
316 =head2 content(%content)
318 The information necessary for the transaction, this tends to vary a
319 little depending on the processor, so we have chosen to use a system
320 which defines specific fields in the frontend which get mapped to the
321 correct fields in the backend. The currently defined fields are:
323 =head3 PROCESSOR FIELDS
329 Your login name to use for authentication to the online processor.
333 Your password to use for authentication to the online processor.
337 =head3 REQUIRED TRANSACTION FIELDS
343 Transaction type, supported types are: CC (credit card), ECHECK
344 (electronic check) and LEC (phone bill billing). Deprecated types
345 are: Visa, MasterCard, American Express, Discover, Check. Not all
346 processors support all transaction types.
350 What action being taken by this transaction. Currently available are:
354 =item Normal Authorization
356 =item Authorization Only
358 =item Post Authorization
360 =item Reverse Authorization
366 =item Recurring Authorization
368 =item Modify Recurring Authorization
370 =item Cancel Recurring Authorization
376 The amount of the transaction. No dollar signs or currency identifiers,
377 just a whole or floating point number (i.e. 26, 26.1 or 26.13).
381 =head3 OPTIONAL TRANSACTION FIELDS
387 If you are prepared to handle partial authorizations
388 (see L<partial_auth_amount()|/"partial_auth_amount()">
389 in L<TRANSACTION RESULT FIELDS|/"TRANSACTION RESULT FIELDS">),
390 pass a true value in this field to enable them.
392 If this flag is not set, a partial authorization will be immediately reversed
397 A description of the transaction (used by some processors to send
398 information to the client, normally not a required field).
402 An invoice number, for your use and not normally required, many
403 processors require this field to be a numeric only field.
407 Purchase order number (normally not required).
411 Tax amount (portion of amount field, not added to it).
415 Freight amount (portion of amount field, not added to it).
419 Duty amount (portion of amount field, not added to it).
423 Tax exempt flag (i.e. TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0).
427 Currency, specified as an ISO 4217 three-letter code, such as USD, CAD, EUR,
428 AUD, DKK, GBP, JPY, NZD, etc.
432 =head3 CUSTOMER INFO FIELDS
438 A customer identifier, again not normally required.
442 The customer's name, your processor may not require this.
448 The customer's first and last name as separate fields.
452 The customer's company name, not normally required.
456 The customer's address (your processor may not require this unless you
457 are requiring AVS Verification).
461 The customer's city (your processor may not require this unless you
462 are requiring AVS Verification).
466 The customer's state (your processor may not require this unless you
467 are requiring AVS Verification).
471 The customer's zip code (your processor may not require this unless
472 you are requiring AVS Verification).
478 =item ship_first_name
494 These shipping address fields may be accepted by your processor.
495 Refer to the description for the corresponding non-ship field for
496 general information on each field.
500 Customer's phone number.
504 Customer's fax number.
508 Customer's email address.
512 IP Address from which the transaction originated.
516 =head3 CREDIT CARD FIELDS
526 Credit card expiration, MM/YY.
530 CVV2 number (also called CVC2 or CID) is a three- or four-digit
531 security code used to reduce credit card fraud.
535 If supported by your gateway, you can pass a card_token instead of a
536 card_number and expiration.
542 #Some card_token schemes implement a challenge/response handshake. In those
543 #cases, this field is used for the response. In most cases the handshake
544 #it taken care of by the gateway module.
548 Track 1 on the magnetic stripe (Card present only)
552 Track 2 on the magnetic stripe (Card present only)
554 =item recurring_billing
556 Recurring billing flag
560 =head3 ELECTRONIC CHECK FIELDS
574 Account type. Can be (case-insensitive): B<Personal Checking>,
575 B<Personal Savings>, B<Business Checking> or B<Business Savings>.
579 Account holder's name.
599 Customer organization type.
603 Customer's social security number.
607 Customer's driver's license number.
611 Customer's date of birth.
615 =head3 RECURRING BILLING FIELDS
621 Interval expresses the amount of time between billings: digits, whitespace
622 and units (currently "days" or "months" in either singular or plural form).
626 The date of the first transaction (used for processors which allow delayed
627 start) expressed as YYYY-MM-DD.
631 The number of cycles of interval length for which billing should occur
632 (inclusive of 'trial periods' if the processor supports recurring billing
633 at more than one rate)
637 =head2 test_transaction()
639 Most processors provide a test mode, where submitted transactions will
640 not actually be charged or added to your batch, calling this function
641 with a true argument will turn that mode on if the processor supports
642 it, or generate a fatal error if the processor does not support a test
643 mode (which is probably better than accidentally making real charges).
647 Providing a true argument to this module will turn on address
648 verification (if the processor supports it).
650 =head1 TRANSACTION SUBMISSION METHOD
654 Submit the transaction to the processor for completion.
656 If there is a gateway communication error or other "meta" , the submit method
657 will throw a fatal exception. You can catch this with eval {} if you would
658 like to treat gateway co
660 =head1 TRANSACTION RESULT METHODS
664 Returns true if the transaction was approved by the gateway, false if
665 it was submitted but not approved, or undef if it has not been
668 =head2 partial_auth_amount()
670 If this transaction was a partial authorization (i.e. successful, but less than
671 the requested amount was processed), then the amount processed is returned in
674 (When is_success is true but this field is empty or 0, that indicates a normal
675 full authorization for the entire requested amount.)
677 =head2 error_message()
679 If the transaction has been submitted but was not accepted, this
680 function will return the provided error message (if any) that the
683 =head2 failure_status()
685 If the transaction failed, it can optionally return a specific failure
686 status (normalized, not gateway-specific). Currently defined statuses
687 are: "expired", "nsf" (non-sufficient funds), "stolen", "pickup",
688 "blacklisted" and "declined" (card/transaction declines only, not
691 Note that not all processor modules support this, and that if supported,
692 it may not be set for all declines.
694 =head2 authorization()
696 If the transaction has been submitted and accepted, this function will
697 provide you with the authorization code that the processor returned.
698 Store this if you would like to run inquiries or refunds on the transaction
701 =head2 order_number()
703 The unique order number for the transaction generated by the gateway. Store
704 this if you would like to run inquiries or refunds on the transaction later.
708 If supported by your gateway, a card_token can be used in a subsequent
709 transaction to refer to a card number.
713 Retrieve or change the fraud score from any Business::FraudDetect plugin
715 =head2 fraud_transaction_id()
717 Retrieve or change the transaction id from any Business::FraudDetect plugin
719 =head2 response_code()
721 =head2 response_headers()
723 =head2 response_page()
725 These three fields are set by some processors (especially those which use
726 HTTPS) when the transaction fails at the communication level rather than
729 response_code is the HTTP response code and message, i.e.
730 '500 Internal Server Error'.
732 response_headers is a hash reference of the response headers
734 response_page is the raw content.
738 Returns the precise result code that the processor returned, these are
739 normally one letter codes that don't mean much unless you understand
740 the protocol they speak, you probably don't need this, but it's there
745 =head2 cvv2_response()
747 =head1 MISCELLANEOUS INTERNAL METHODS
749 =head2 transaction_type()
751 Retrieve the transaction type (the 'type' argument to contents()).
752 Generally only used internally, but provided in case it is useful.
756 Retrieve or change the processor submission server address (CHANGE AT
761 Retrieve or change the processor submission port (CHANGE AT YOUR OWN
766 Retrieve or change the processor submission path (CHANGE AT YOUR OWN
769 =head1 HELPER METHODS FOR GATEWAY MODULE AUTHORS
771 =head2 build_subs( @sub_names )
773 Build setter/getter subroutines for new return values.
775 =head2 get_fields( @fields )
777 Get the named fields if they are defined.
779 =head2 remap_fields( %map )
781 Remap field content (and stuff it back into content).
783 =head2 required_fields( @fields )
785 Croaks if any of the required fields are not present.
789 =head2 silly_bool( $value )
791 Returns 0 if the value starts with y, Y, t or T.
792 Returns 1 if the value starts with n, N, f or F.
793 Otherwise returns the value itself.
795 Use this for handling boolean content like tax_exempt.
801 Jason Kohles, email@jasonkohles.com
805 Ivan Kohler <ivan-business-onlinepayment@420.am>
807 Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
811 Copyright (c) 1999-2004 Jason Kohles
812 Copyright (c) 2004 Ivan Kohler
813 Copyright (c) 2007-2015 Freeside Internet Services, Inc.
817 This program is free software; you can redistribute it and/or modify it under
818 the same terms as Perl itself.
822 Homepage: http://perl.business/onlinepayment
824 Development: http://perl.business/onlinepayment/ng.html
828 Please direct current development questions, patches, etc. to the mailing list:
829 http://420.am/cgi-bin/mailman/listinfo/bop-devel/
833 The code is available from our public git repository:
835 git clone git://git.freeside.biz/Business-OnlinePayment.git
839 http://freeside.biz/gitweb/?p=Business-OnlinePayment.git
841 http://freeside.biz/gitlist/Business-OnlinePayment.git
843 Many (but by no means all!) processor plugins are also available in the same
846 http://freeside.biz/gitweb/
848 http://freeside.biz/gitlist/
852 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
853 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
854 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
858 http://perl.business/onlinepayment
860 For verification of credit card checksums, see L<Business::CreditCard>.