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 = ();
42 __PACKAGE__->build_subs(@methods);
47 ( my $gw = $class ) =~ s/^Business::OnlinePayment:://;
49 'info_compat' => '0.00',
50 'gateway_name' => $gw,
51 'module_notes' => "Module does not yet provide info.",
55 #allow classes to declare info in a flexible way, but return normalized info
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';
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 );
73 my $class = shift; #class or object
74 my $info = $class->_info;
77 exists($_info_handler{$key})
78 ? &{ $_info_handler{$key} }( $class, $info->{$key} )
81 wantarray ? ( keys %$info ) : [ keys %$info ];
86 my($class,$processor,%data) = @_;
88 croak("unspecified processor") unless $processor;
90 my $subclass = "${class}::$processor";
92 croak("unknown processor $processor ($@)") if $@;
94 my $self = bless {processor => $processor}, $subclass;
96 if($self->can("set_defaults")) {
97 $self->set_defaults(%data);
100 foreach(keys %data) {
102 my $value = $data{$_};
104 $self->build_subs($key);
108 # "wrap" submit with _pre_submit only once
109 unless ( $Presubmit_Added{$subclass} ) {
110 my $real_submit = $subclass->can('submit');
112 no warnings 'redefine';
115 *{"${subclass}::submit"} = sub {
117 return unless $self->_pre_submit(@_);
118 return $real_submit->($self, @_);
126 my ($self, $risk_transaction) = @_;
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()) {
138 $self->error_message('Excessive risk from risk management');
141 $self->error_message('Error in risk detection stage: ' . $risk_transaction->error_message);
143 $self->is_success(0);
147 my @Fraud_Class_Path = qw(Business::OnlinePayment Business::FraudDetect);
151 my $fraud_detection = $self->fraud_detect();
153 # early return if user does not want optional risk mgt
154 return 1 unless $fraud_detection;
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 ()";
161 croak("error loading fraud_detection module ($@)")
162 unless ( $@ =~ m/^Can\'t locate/ );
164 my $risk_tx = bless( { processor => $fraud_detection }, $subclass );
165 if ($risk_tx->can('set_defaults')) {
166 $risk_tx->set_defaults();
168 $risk_tx->_glean_parameters_from_parent($self);
169 return $self->_risk_detect($risk_tx);
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)");
178 my($self,%params) = @_;
181 if($params{'type'}) { $self->transaction_type($params{'type'}); }
182 %{$self->{'_content'}} = %params;
184 return exists $self->{'_content'} ? %{$self->{'_content'}} : ();
187 sub required_fields {
188 my($self,@fields) = @_;
191 my %content = $self->content();
193 push(@missing, $_) unless exists $content{$_};
196 croak("missing required field(s): " . join(", ", @missing) . "\n")
201 my($self, @fields) = @_;
203 my %content = $self->content();
206 #foreach(@fields) { $new{$_} = $content{$_}; }
208 map { $_ => $content{$_} } grep defined $content{$_}, @fields;
214 my %content = $self->content();
215 foreach( keys %map ) {
216 $content{$map{$_}} = $content{$_};
218 $self->content(%content);
224 croak("Processor subclass did not override submit function");
230 my %content = $self->content();
232 foreach(sort keys %content) {
233 $dump .= "$_ = $content{$_}\n";
238 # didnt use AUTOLOAD because Net::SSLeay::AUTOLOAD passes right to
239 # AutoLoader::AUTOLOAD, instead of passing up the chain
244 next if($self->can($_));
245 eval "sub $_ { my \$self = shift; if(\@_) { \$self->{$_} = shift; } return \$self->{$_}; }";
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;
266 Business::OnlinePayment - Perl extension for online payment processing
270 use Business::OnlinePayment;
272 my $transaction = new Business::OnlinePayment($processor, %processor_info);
273 $transaction->content(
276 card_number => '1234123412341238',
277 expiration => '06/15',
278 name => 'John Q Doe',
281 eval { $transaction->submit(); };
285 print "$processor error: $@\n";
289 if ( $transaction->is_success() ) {
290 print "Card processed successfully: ". $transaction->authorization()."\n";
292 print "Card was rejected: ". $transaction->error_message(). "\n";
299 Business::OnlinePayment is a generic module for processing payments
300 through online credit card processors, electronic cash systems, etc.
304 =head2 new($processor, %processor_options)
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.
315 =head1 TRANSACTION SETUP METHODS
317 =head2 content(%content)
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:
324 =head3 PROCESSOR FIELDS
330 Your login name to use for authentication to the online processor.
334 Your password to use for authentication to the online processor.
338 =head3 REQUIRED TRANSACTION FIELDS
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.
351 What action being taken by this transaction. Currently available are:
355 =item Normal Authorization
357 =item Authorization Only
359 =item Post Authorization
361 =item Reverse Authorization
367 =item Recurring Authorization
369 =item Modify Recurring Authorization
371 =item Cancel Recurring Authorization
377 The amount of the transaction. No dollar signs or currency identifiers,
378 just a whole or floating point number (i.e. 26, 26.1 or 26.13).
382 =head3 OPTIONAL TRANSACTION FIELDS
388 If you are prepared to handle partial authorizations
389 (see L<partial_auth_amount()|/"partial_auth_amount()">
390 in L<TRANSACTION RESULT FIELDS|/"TRANSACTION RESULT FIELDS">),
391 pass a true value in this field to enable them.
393 If this flag is not set, a partial authorization will be immediately reversed
398 A description of the transaction (used by some processors to send
399 information to the client, normally not a required field).
403 An invoice number, for your use and not normally required, many
404 processors require this field to be a numeric only field.
408 Purchase order number (normally not required).
412 Tax amount (portion of amount field, not added to it).
416 Freight amount (portion of amount field, not added to it).
420 Duty amount (portion of amount field, not added to it).
424 Tax exempt flag (i.e. TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0).
428 Currency, specified as an ISO 4217 three-letter code, such as USD, CAD, EUR,
429 AUD, DKK, GBP, JPY, NZD, etc.
433 =head3 CUSTOMER INFO FIELDS
439 A customer identifier, again not normally required.
443 The customer's name, your processor may not require this.
449 The customer's first and last name as separate fields.
453 The customer's company name, not normally required.
457 The customer's address (your processor may not require this unless you
458 are requiring AVS Verification).
462 The customer's city (your processor may not require this unless you
463 are requiring AVS Verification).
467 The customer's state (your processor may not require this unless you
468 are requiring AVS Verification).
472 The customer's zip code (your processor may not require this unless
473 you are requiring AVS Verification).
479 =item ship_first_name
495 These shipping address fields may be accepted by your processor.
496 Refer to the description for the corresponding non-ship field for
497 general information on each field.
501 Customer's phone number.
505 Customer's fax number.
509 Customer's email address.
513 IP Address from which the transaction originated.
517 =head3 CREDIT CARD FIELDS
527 Credit card expiration, MM/YY.
531 CVV2 number (also called CVC2 or CID) is a three- or four-digit
532 security code used to reduce credit card fraud.
536 If supported by your gateway, you can pass a card_token instead of a
537 card_number and expiration.
543 #Some card_token schemes implement a challenge/response handshake. In those
544 #cases, this field is used for the response. In most cases the handshake
545 #it taken care of by the gateway module.
549 Track 1 on the magnetic stripe (Card present only)
553 Track 2 on the magnetic stripe (Card present only)
555 =item recurring_billing
557 Recurring billing flag
561 =head3 ELECTRONIC CHECK FIELDS
575 Account type. Can be (case-insensitive): B<Personal Checking>,
576 B<Personal Savings>, B<Business Checking> or B<Business Savings>.
580 Account holder's name.
600 Customer organization type.
604 Customer's social security number.
608 Customer's driver's license number.
612 Customer's date of birth.
616 =head3 RECURRING BILLING FIELDS
622 Interval expresses the amount of time between billings: digits, whitespace
623 and units (currently "days" or "months" in either singular or plural form).
627 The date of the first transaction (used for processors which allow delayed
628 start) expressed as YYYY-MM-DD.
632 The number of cycles of interval length for which billing should occur
633 (inclusive of 'trial periods' if the processor supports recurring billing
634 at more than one rate)
638 =head2 test_transaction()
640 Most processors provide a test mode, where submitted transactions will
641 not actually be charged or added to your batch, calling this function
642 with a true argument will turn that mode on if the processor supports
643 it, or generate a fatal error if the processor does not support a test
644 mode (which is probably better than accidentally making real charges).
648 Providing a true argument to this module will turn on address
649 verification (if the processor supports it).
651 =head1 TRANSACTION SUBMISSION METHOD
655 Submit the transaction to the processor for completion.
657 If there is a gateway communication error or other "meta" , the submit method
658 will throw a fatal exception. You can catch this with eval {} if you would
659 like to treat gateway co
661 =head1 TRANSACTION RESULT METHODS
665 Returns true if the transaction was approved by the gateway, false if
666 it was submitted but not approved, or undef if it has not been
669 =head2 partial_auth_amount()
671 If this transaction was a partial authorization (i.e. successful, but less than
672 the requested amount was processed), then the amount processed is returned in
675 (When is_success is true but this field is empty or 0, that indicates a normal
676 full authorization for the entire requested amount.)
678 =head2 error_message()
680 If the transaction has been submitted but was not accepted, this
681 function will return the provided error message (if any) that the
684 =head2 failure_status()
686 If the transaction failed, it can optionally return a specific failure
687 status (normalized, not gateway-specific). Currently defined statuses
688 are: "expired", "nsf" (non-sufficient funds), "stolen", "pickup",
689 "blacklisted" and "declined" (card/transaction declines only, not
692 Note that not all processor modules support this, and that if supported,
693 it may not be set for all declines.
695 =head2 authorization()
697 If the transaction has been submitted and accepted, this function will
698 provide you with the authorization code that the processor returned.
699 Store this if you would like to run inquiries or refunds on the transaction
702 =head2 order_number()
704 The unique order number for the transaction generated by the gateway. Store
705 this if you would like to run inquiries or refunds on the transaction later.
709 If supported by your gateway, a card_token can be used in a subsequent
710 transaction to refer to a card number.
714 Transaction date, as returned by the gateway. Required by some gateways
715 for follow-up transactions.
719 Retrieve or change the fraud score from any Business::FraudDetect plugin
721 =head2 fraud_transaction_id()
723 Retrieve or change the transaction id from any Business::FraudDetect plugin
725 =head2 response_code()
727 =head2 response_headers()
729 =head2 response_page()
731 These three fields are set by some processors (especially those which use
732 HTTPS) when the transaction fails at the communication level rather than
735 response_code is the HTTP response code and message, i.e.
736 '500 Internal Server Error'.
738 response_headers is a hash reference of the response headers
740 response_page is the raw content.
744 Returns the precise result code that the processor returned, these are
745 normally one letter codes that don't mean much unless you understand
746 the protocol they speak, you probably don't need this, but it's there
751 =head2 cvv2_response()
753 =head1 MISCELLANEOUS INTERNAL METHODS
755 =head2 transaction_type()
757 Retrieve the transaction type (the 'type' argument to contents()).
758 Generally only used internally, but provided in case it is useful.
762 Retrieve or change the processor submission server address (CHANGE AT
767 Retrieve or change the processor submission port (CHANGE AT YOUR OWN
772 Retrieve or change the processor submission path (CHANGE AT YOUR OWN
775 =head1 HELPER METHODS FOR GATEWAY MODULE AUTHORS
777 =head2 build_subs( @sub_names )
779 Build setter/getter subroutines for new return values.
781 =head2 get_fields( @fields )
783 Get the named fields if they are defined.
785 =head2 remap_fields( %map )
787 Remap field content (and stuff it back into content).
789 =head2 required_fields( @fields )
791 Croaks if any of the required fields are not present.
795 =head2 silly_bool( $value )
797 Returns 1 if the value starts with y, Y, t or T.
798 Returns 0 if the value starts with n, N, f or F.
799 Otherwise returns the value itself.
801 Use this for handling boolean content like tax_exempt.
807 Jason Kohles, email@jasonkohles.com
811 Ivan Kohler <ivan-business-onlinepayment@420.am>
813 Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
817 Copyright (c) 1999-2004 Jason Kohles
818 Copyright (c) 2004 Ivan Kohler
819 Copyright (c) 2007-2015 Freeside Internet Services, Inc.
823 This program is free software; you can redistribute it and/or modify it under
824 the same terms as Perl itself.
828 Homepage: http://perl.business/onlinepayment
830 Development: http://perl.business/onlinepayment/ng.html
834 Please direct current development questions, patches, etc. to the mailing list:
835 http://420.am/cgi-bin/mailman/listinfo/bop-devel/
839 The code is available from our public git repository:
841 git clone git://git.freeside.biz/Business-OnlinePayment.git
845 http://freeside.biz/gitweb/?p=Business-OnlinePayment.git
847 http://freeside.biz/gitlist/Business-OnlinePayment.git
849 Many (but by no means all!) processor plugins are also available in the same
852 http://freeside.biz/gitweb/
854 http://freeside.biz/gitlist/
858 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
859 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
860 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
864 http://perl.business/onlinepayment
866 For verification of credit card checksums, see L<Business::CreditCard>.