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
369 =item Recurring Authorization
371 =item Modify Recurring Authorization
373 =item Cancel Recurring Authorization
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).
384 =head3 OPTIONAL TRANSACTION FIELDS
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.
395 If this flag is not set, a partial authorization will be immediately reversed
400 A description of the transaction (used by some processors to send
401 information to the client, normally not a required field).
405 An invoice number, for your use and not normally required, many
406 processors require this field to be a numeric only field.
410 Purchase order number (normally not required).
414 Tax amount (portion of amount field, not added to it).
418 Freight amount (portion of amount field, not added to it).
422 Duty amount (portion of amount field, not added to it).
426 Tax exempt flag (i.e. TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0).
430 Currency, specified as an ISO 4217 three-letter code, such as USD, CAD, EUR,
431 AUD, DKK, GBP, JPY, NZD, etc.
435 =head3 CUSTOMER INFO FIELDS
441 A customer identifier, again not normally required.
445 The customer's name, your processor may not require this.
451 The customer's first and last name as separate fields.
455 The customer's company name, not normally required.
459 The customer's address (your processor may not require this unless you
460 are requiring AVS Verification).
464 The customer's city (your processor may not require this unless you
465 are requiring AVS Verification).
469 The customer's state (your processor may not require this unless you
470 are requiring AVS Verification).
474 The customer's zip code (your processor may not require this unless
475 you are requiring AVS Verification).
481 =item ship_first_name
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.
503 Customer's phone number.
507 Customer's fax number.
511 Customer's email address.
515 IP Address from which the transaction originated.
519 =head3 CREDIT CARD FIELDS
529 Credit card expiration, MM/YY.
533 CVV2 number (also called CVC2 or CID) is a three- or four-digit
534 security code used to reduce credit card fraud.
538 If supported by your gateway, you can pass a card_token instead of a
539 card_number and expiration.
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.
551 Track 1 on the magnetic stripe (Card present only)
555 Track 2 on the magnetic stripe (Card present only)
557 =item recurring_billing
559 Recurring billing flag
563 =head3 ELECTRONIC CHECK FIELDS
577 Account type. Can be (case-insensitive): B<Personal Checking>,
578 B<Personal Savings>, B<Business Checking> or B<Business Savings>.
582 Account holder's name.
602 Customer organization type.
606 Customer's social security number.
610 Customer's driver's license number.
614 Customer's date of birth.
618 =head3 FOLLOW-UP TRANSACTION FIELDS
620 These fields are used in follow-up transactions related to an original
621 transaction (Post Authorization, Reverse Authorization, Void, Credit).
633 =head3 RECURRING BILLING FIELDS
639 Interval expresses the amount of time between billings: digits, whitespace
640 and units (currently "days" or "months" in either singular or plural form).
644 The date of the first transaction (used for processors which allow delayed
645 start) expressed as YYYY-MM-DD.
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)
655 =head2 test_transaction()
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).
665 Providing a true argument to this module will turn on address
666 verification (if the processor supports it).
668 =head1 TRANSACTION SUBMISSION METHOD
672 Submit the transaction to the processor for completion.
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
678 =head1 TRANSACTION RESULT METHODS
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
686 =head2 partial_auth_amount()
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
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.)
695 =head2 error_message()
697 If the transaction has been submitted but was not accepted, this
698 function will return the provided error message (if any) that the
701 =head2 failure_status()
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
709 Note that not all processor modules support this, and that if supported,
710 it may not be set for all declines.
712 =head2 authorization()
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
719 =head2 order_number()
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.
726 If supported by your gateway, a card_token can be used in a subsequent
727 transaction to refer to a card number.
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.
737 Retrieve or change the fraud score from any Business::FraudDetect plugin
739 =head2 fraud_transaction_id()
741 Retrieve or change the transaction id from any Business::FraudDetect plugin
743 =head2 response_code()
745 =head2 response_headers()
747 =head2 response_page()
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
753 response_code is the HTTP response code and message, i.e.
754 '500 Internal Server Error'.
756 response_headers is a hash reference of the response headers
758 response_page is the raw content.
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
769 =head2 cvv2_response()
771 =head1 MISCELLANEOUS INTERNAL METHODS
773 =head2 transaction_type()
775 Retrieve the transaction type (the 'type' argument to contents()).
776 Generally only used internally, but provided in case it is useful.
780 Retrieve or change the processor submission server address (CHANGE AT
785 Retrieve or change the processor submission port (CHANGE AT YOUR OWN
790 Retrieve or change the processor submission path (CHANGE AT YOUR OWN
793 =head1 HELPER METHODS FOR GATEWAY MODULE AUTHORS
795 =head2 build_subs( @sub_names )
797 Build setter/getter subroutines for new return values.
799 =head2 get_fields( @fields )
801 Get the named fields if they are defined.
803 =head2 remap_fields( %map )
805 Remap field content (and stuff it back into content).
807 =head2 required_fields( @fields )
809 Croaks if any of the required fields are not present.
813 =head2 silly_bool( $value )
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.
819 Use this for handling boolean content like tax_exempt.
825 Jason Kohles, email@jasonkohles.com
829 Ivan Kohler <ivan-business-onlinepayment@420.am>
831 Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
835 Copyright (c) 1999-2004 Jason Kohles
836 Copyright (c) 2004 Ivan Kohler
837 Copyright (c) 2007-2016 Freeside Internet Services, Inc.
841 This program is free software; you can redistribute it and/or modify it under
842 the same terms as Perl itself.
846 Homepage: http://perl.business/onlinepayment
848 Development: http://perl.business/onlinepayment/ng.html
852 Please direct current development questions, patches, etc. to the mailing list:
853 http://420.am/cgi-bin/mailman/listinfo/bop-devel/
857 The code is available from our public git repository:
859 git clone git://git.freeside.biz/Business-OnlinePayment.git
863 http://freeside.biz/gitweb/?p=Business-OnlinePayment.git
865 http://freeside.biz/gitlist/Business-OnlinePayment.git
867 Many (but by no means all!) processor plugins are also available in the same
870 http://freeside.biz/gitweb/
872 http://freeside.biz/gitlist/
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.
882 http://perl.business/onlinepayment
884 For verification of credit card checksums, see L<Business::CreditCard>.