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 ( my $gw = $class ) =~ s/^Business::OnlinePayment:://;
43 'info_compat' => '0.00',
44 'gateway_name' => $gw,
45 'module_notes' => "Module does not yet provide info.",
49 #allow classes to declare info in a flexible way, but return normalized info
51 'supported_types' => sub {
52 my( $class, $v ) = @_;
53 my $types = ref($v) ? $v : defined($v) ? [ $v ] : [];
54 $types = { map { $_=>1 } @$types } if ref($types) eq 'ARRAY';
57 'supported_actions' => sub {
58 my( $class, $v ) = @_;
59 return %$v if ref($v) eq 'HASH';
60 $v = [ $v ] unless ref($v);
61 my $types = $class->info('supported_types') || {};
62 ( map { $_ => $v } keys %$types );
67 my $class = shift; #class or object
68 my $info = $class->_info;
71 exists($_info_handler{$key})
72 ? &{ $_info_handler{$key} }( $class, $info->{$key} )
75 wantarray ? ( keys %$info ) : [ keys %$info ];
80 my($class,$processor,%data) = @_;
82 croak("unspecified processor") unless $processor;
84 my $subclass = "${class}::$processor";
86 croak("unknown processor $processor ($@)") if $@;
88 my $self = bless {processor => $processor}, $subclass;
89 $self->build_subs(@methods);
91 if($self->can("set_defaults")) {
92 $self->set_defaults(%data);
97 my $value = $data{$_};
99 $self->build_subs($key);
103 # "wrap" submit with _pre_submit only once
104 unless ( $Presubmit_Added{$subclass} ) {
105 my $real_submit = $subclass->can('submit');
107 no warnings 'redefine';
110 *{"${subclass}::submit"} = sub {
112 return unless $self->_pre_submit(@_);
113 return $real_submit->($self, @_);
121 my ($self, $risk_transaction) = @_;
123 my %parent_content = $self->content();
124 $parent_content{action} = 'Fraud Detect';
125 $risk_transaction->content( %parent_content );
126 $risk_transaction->submit();
127 if ($risk_transaction->is_success()) {
128 $self->fraud_score( $risk_transaction->fraud_score );
129 $self->fraud_transaction_id( $risk_transaction->fraud_transaction_id );
130 if ( $risk_transaction->fraud_score <= $self->maximum_fraud_score()) {
133 $self->error_message('Excessive risk from risk management');
136 $self->error_message('Error in risk detection stage: ' . $risk_transaction->error_message);
138 $self->is_success(0);
142 my @Fraud_Class_Path = qw(Business::OnlinePayment Business::FraudDetect);
146 my $fraud_detection = $self->fraud_detect();
148 # early return if user does not want optional risk mgt
149 return 1 unless $fraud_detection;
151 # Search for an appropriate FD module
152 foreach my $fraud_class ( @Fraud_Class_Path ) {
153 my $subclass = $fraud_class . "::" . $fraud_detection;
154 eval "use $subclass ()";
156 croak("error loading fraud_detection module ($@)")
157 unless ( $@ =~ m/^Can\'t locate/ );
159 my $risk_tx = bless( { processor => $fraud_detection }, $subclass );
160 $risk_tx->build_subs(@methods);
161 if ($risk_tx->can('set_defaults')) {
162 $risk_tx->set_defaults();
164 $risk_tx->_glean_parameters_from_parent($self);
165 return $self->_risk_detect($risk_tx);
168 croak("Unable to locate fraud_detection module $fraud_detection"
169 . " in \@INC under Fraud_Class_Path (\@Fraud_Class_Path"
170 . " contains: @Fraud_Class_Path) (\@INC contains: @INC)");
174 my($self,%params) = @_;
177 if($params{'type'}) { $self->transaction_type($params{'type'}); }
178 %{$self->{'_content'}} = %params;
180 return exists $self->{'_content'} ? %{$self->{'_content'}} : ();
183 sub required_fields {
184 my($self,@fields) = @_;
187 my %content = $self->content();
189 push(@missing, $_) unless exists $content{$_};
192 croak("missing required field(s): " . join(", ", @missing) . "\n")
197 my($self, @fields) = @_;
199 my %content = $self->content();
202 #foreach(@fields) { $new{$_} = $content{$_}; }
204 map { $_ => $content{$_} } grep defined $content{$_}, @fields;
210 my %content = $self->content();
211 foreach( keys %map ) {
212 $content{$map{$_}} = $content{$_};
214 $self->content(%content);
220 croak("Processor subclass did not override submit function");
226 my %content = $self->content();
228 foreach(sort keys %content) {
229 $dump .= "$_ = $content{$_}\n";
234 # didnt use AUTOLOAD because Net::SSLeay::AUTOLOAD passes right to
235 # AutoLoader::AUTOLOAD, instead of passing up the chain
240 next if($self->can($_));
241 eval "sub $_ { my \$self = shift; if(\@_) { \$self->{$_} = shift; } return \$self->{$_}; }";
248 my( $self, $value ) = @_;
249 return 1 if $value =~ /^[yt]/i;
250 return 0 if $value =~ /^[fn]/i;
251 #return 1 if $value == 1;
252 #return 0 if $value == 0;
262 Business::OnlinePayment - Perl extension for online payment processing
266 use Business::OnlinePayment;
268 my $transaction = new Business::OnlinePayment($processor, %processor_info);
269 $transaction->content(
272 card_number => '1234123412341238',
273 expiration => '06/15',
274 name => 'John Q Doe',
276 $transaction->submit();
278 if($transaction->is_success()) {
279 print "Card processed successfully: ", $transaction->authorization(), "\n";
281 print "Card was rejected: ", $transaction->error_message(), "\n";
286 Business::OnlinePayment is a generic module for processing payments
287 through online credit card processors, electronic cash systems, etc.
291 =head2 new($processor, %processor_options)
293 Create a new Business::OnlinePayment object, $processor is required,
294 and defines the online processor to use. If necessary, processor
295 options can be specified, currently supported options are 'Server',
296 'Port', and 'Path', which specify how to find the online processor
297 (https://server:port/path), but individual processor modules should
298 supply reasonable defaults for this information, override the defaults
299 only if absolutely necessary (especially path), as the processor
300 module was probably written with a specific target script in mind.
302 =head1 TRANSACTION SETUP METHODS
304 =head2 content(%content)
306 The information necessary for the transaction, this tends to vary a
307 little depending on the processor, so we have chosen to use a system
308 which defines specific fields in the frontend which get mapped to the
309 correct fields in the backend. The currently defined fields are:
311 =head3 PROCESSOR FIELDS
317 Your login name to use for authentication to the online processor.
321 Your password to use for authentication to the online processor.
325 =head3 REQUIRED TRANSACTION FIELDS
331 Transaction type, supported types are: CC (credit card), ECHECK
332 (electronic check) and LEC (phone bill billing). Deprecated types
333 are: Visa, MasterCard, American Express, Discover, Check. Not all
334 processors support all transaction types.
338 What action being taken by this transaction. Currently available are:
342 =item Normal Authorization
344 =item Authorization Only
346 =item Post Authorization
348 =item Reverse Authorization
354 =item Recurring Authorization
356 =item Modify Recurring Authorization
358 =item Cancel Recurring Authorization
364 The amount of the transaction. No dollar signs or currency identifiers,
365 just a whole or floating point number (i.e. 26, 26.1 or 26.13).
369 =head3 OPTIONAL TRANSACTION FIELDS
375 A description of the transaction (used by some processors to send
376 information to the client, normally not a required field).
380 An invoice number, for your use and not normally required, many
381 processors require this field to be a numeric only field.
385 Purchase order number (normally not required).
389 Tax amount (portion of amount field, not added to it).
393 Freight amount (portion of amount field, not added to it).
397 Duty amount (portion of amount field, not added to it).
401 Tax exempt flag (i.e. TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0).
405 Currency, specified as an ISO 4217 three-letter code, such as USD, CAD, EUR,
406 AUD, DKK, GBP, JPY, NZD, etc.
410 =head3 CUSTOMER INFO FIELDS
416 A customer identifier, again not normally required.
420 The customer's name, your processor may not require this.
426 The customer's first and last name as separate fields.
430 The customer's company name, not normally required.
434 The customer's address (your processor may not require this unless you
435 are requiring AVS Verification).
439 The customer's city (your processor may not require this unless you
440 are requiring AVS Verification).
444 The customer's state (your processor may not require this unless you
445 are requiring AVS Verification).
449 The customer's zip code (your processor may not require this unless
450 you are requiring AVS Verification).
456 =item ship_first_name
472 These shipping address fields may be accepted by your processor.
473 Refer to the description for the corresponding non-ship field for
474 general information on each field.
478 Customer's phone number.
482 Customer's fax number.
486 Customer's email address.
490 IP Address from which the transaction originated.
494 =head3 CREDIT CARD FIELDS
504 Credit card expiration, MM/YY.
508 CVV2 number (also called CVC2 or CID) is a three- or four-digit
509 security code used to reduce credit card fraud.
513 If supported by your gateway, you can pass a card_token instead of a
514 card_number and expiration.
520 #Some card_token schemes implement a challenge/response handshake. In those
521 #cases, this field is used for the response. In most cases the handshake
522 #it taken care of by the gateway module.
526 Track 1 on the magnetic stripe (Card present only)
530 Track 2 on the magnetic stripe (Card present only)
532 =item recurring_billing
534 Recurring billing flag
538 =head3 ELECTRONIC CHECK FIELDS
552 Account type. Can be (case-insensitive): B<Personal Checking>,
553 B<Personal Savings>, B<Business Checking> or B<Business Savings>.
557 Account holder's name.
577 Customer organization type.
581 Customer's social security number.
585 Customer's driver's license number.
589 Customer's date of birth.
593 =head3 RECURRING BILLING FIELDS
599 Interval expresses the amount of time between billings: digits, whitespace
600 and units (currently "days" or "months" in either singular or plural form).
604 The date of the first transaction (used for processors which allow delayed
605 start) expressed as YYYY-MM-DD.
609 The number of cycles of interval length for which billing should occur
610 (inclusive of 'trial periods' if the processor supports recurring billing
611 at more than one rate)
615 =head2 test_transaction()
617 Most processors provide a test mode, where submitted transactions will
618 not actually be charged or added to your batch, calling this function
619 with a true argument will turn that mode on if the processor supports
620 it, or generate a fatal error if the processor does not support a test
621 mode (which is probably better than accidentally making real charges).
625 Providing a true argument to this module will turn on address
626 verification (if the processor supports it).
628 =head1 TRANSACTION SUBMISSION METHOD
632 Submit the transaction to the processor for completion
634 =head1 TRANSACTION RESULT METHODS
638 Returns true if the transaction was approved by the gateway, false if
639 it was submitted but not approved, or undef if it has not been
642 =head2 error_message()
644 If the transaction has been submitted but was not accepted, this
645 function will return the provided error message (if any) that the
648 =head2 failure_status()
650 If the transaction failed, it can optionally return a specific failure
651 status (normalized, not gateway-specific). Currently defined statuses
652 are: "expired", "nsf" (non-sufficient funds), "stolen", "pickup",
653 "blacklisted" and "declined" (card/transaction declines only, not
656 Note that (as of Aug 2006) this is only supported by some of the
657 newest processor modules, and that, even if supported, a failure
658 status is an entirely optional field that is only set for specific
661 =head2 authorization()
663 If the transaction has been submitted and accepted, this function will
664 provide you with the authorization code that the processor returned.
665 Store this if you would like to run inquiries or refunds on the transaction
668 =head2 order_number()
670 The unique order number for the transaction generated by the gateway. Store
671 this if you would like to run inquiries or refunds on the transaction later.
675 If supported by your gateway, a card_token can be used in a subsequent
676 transaction to refer to a card number.
680 Retrieve or change the fraud score from any Business::FraudDetect plugin
682 =head2 fraud_transaction_id()
684 Retrieve or change the transaction id from any Business::FraudDetect plugin
686 =head2 response_code()
688 =head2 response_headers()
690 =head2 response_page()
692 These three fields are set by some processors (especially those which use
693 HTTPS) when the transaction fails at the communication level rather than
696 response_code is the HTTP response code and message, i.e.
697 '500 Internal Server Error'.
699 response_headers is a hash reference of the response headers
701 response_page is the raw content.
705 Returns the precise result code that the processor returned, these are
706 normally one letter codes that don't mean much unless you understand
707 the protocol they speak, you probably don't need this, but it's there
712 =head2 cvv2_response()
714 =head1 MISCELLANEOUS INTERNAL METHODS
716 =head2 transaction_type()
718 Retrieve the transaction type (the 'type' argument to contents()).
719 Generally only used internally, but provided in case it is useful.
723 Retrieve or change the processor submission server address (CHANGE AT
728 Retrieve or change the processor submission port (CHANGE AT YOUR OWN
733 Retrieve or change the processor submission path (CHANGE AT YOUR OWN
736 =head1 HELPER METHODS FOR GATEWAY MODULE AUTHORS
738 =head2 build_subs( @sub_names )
740 Build setter/getter subroutines for new return values.
742 =head2 get_fields( @fields )
744 Get the named fields if they are defined.
746 =head2 remap_fields( %map )
748 Remap field content (and stuff it back into content).
750 =head2 required_fields( @fields )
752 Croaks if any of the required fields are not present.
756 =head2 silly_bool( $value )
758 Returns 0 if the value starts with y, Y, t or T.
759 Returns 1 if the value starts with n, N, f or F.
760 Otherwise returns the value itself.
762 Use this for handling boolean content like tax_exempt.
768 Jason Kohles, email@jasonkohles.com
772 Ivan Kohler <ivan-business-onlinepayment@420.am>
774 Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
778 Copyright (c) 1999-2004 Jason Kohles
779 Copyright (c) 2004 Ivan Kohler
780 Copyright (c) 2007-2012 Freeside Internet Services, Inc.
784 This program is free software; you can redistribute it and/or modify it under
785 the same terms as Perl itself.
789 Homepage: http://420.am/business-onlinepayment/
791 Development: http://420.am/business-onlinepayment/ng.html
795 Please direct current development questions, patches, etc. to the mailing list:
796 http://420.am/cgi-bin/mailman/listinfo/bop-devel/
800 The code is available from our public CVS repository:
802 export CVSROOT=":pserver:anonymous@cvs.freeside.biz:/home/cvs/cvsroot"
804 # The password for the user `anonymous' is `anonymous'.
805 cvs checkout Business-OnlinePayment
809 http://freeside.biz/cgi-bin/viewvc.cgi/Business-OnlinePayment/
811 Many (but by no means all!) processor plugins are also available in the same
814 http://freeside.biz/cgi-bin/viewvc.cgi/
818 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
819 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
820 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
824 http://420.am/business-onlinepayment/
826 For verification of credit card checksums, see L<Business::CreditCard>.