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 Set true to accept a partial authorization. If this flag is not set, a partial
389 authorization will be immediately reversed or voided.
393 A description of the transaction (used by some processors to send
394 information to the client, normally not a required field).
398 An invoice number, for your use and not normally required, many
399 processors require this field to be a numeric only field.
403 Purchase order number (normally not required).
407 Tax amount (portion of amount field, not added to it).
411 Freight amount (portion of amount field, not added to it).
415 Duty amount (portion of amount field, not added to it).
419 Tax exempt flag (i.e. TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0).
423 Currency, specified as an ISO 4217 three-letter code, such as USD, CAD, EUR,
424 AUD, DKK, GBP, JPY, NZD, etc.
428 =head3 CUSTOMER INFO FIELDS
434 A customer identifier, again not normally required.
438 The customer's name, your processor may not require this.
444 The customer's first and last name as separate fields.
448 The customer's company name, not normally required.
452 The customer's address (your processor may not require this unless you
453 are requiring AVS Verification).
457 The customer's city (your processor may not require this unless you
458 are requiring AVS Verification).
462 The customer's state (your processor may not require this unless you
463 are requiring AVS Verification).
467 The customer's zip code (your processor may not require this unless
468 you are requiring AVS Verification).
474 =item ship_first_name
490 These shipping address fields may be accepted by your processor.
491 Refer to the description for the corresponding non-ship field for
492 general information on each field.
496 Customer's phone number.
500 Customer's fax number.
504 Customer's email address.
508 IP Address from which the transaction originated.
512 =head3 CREDIT CARD FIELDS
522 Credit card expiration, MM/YY.
526 CVV2 number (also called CVC2 or CID) is a three- or four-digit
527 security code used to reduce credit card fraud.
531 If supported by your gateway, you can pass a card_token instead of a
532 card_number and expiration.
538 #Some card_token schemes implement a challenge/response handshake. In those
539 #cases, this field is used for the response. In most cases the handshake
540 #it taken care of by the gateway module.
544 Track 1 on the magnetic stripe (Card present only)
548 Track 2 on the magnetic stripe (Card present only)
550 =item recurring_billing
552 Recurring billing flag
556 =head3 ELECTRONIC CHECK FIELDS
570 Account type. Can be (case-insensitive): B<Personal Checking>,
571 B<Personal Savings>, B<Business Checking> or B<Business Savings>.
575 Account holder's name.
595 Customer organization type.
599 Customer's social security number.
603 Customer's driver's license number.
607 Customer's date of birth.
611 =head3 RECURRING BILLING FIELDS
617 Interval expresses the amount of time between billings: digits, whitespace
618 and units (currently "days" or "months" in either singular or plural form).
622 The date of the first transaction (used for processors which allow delayed
623 start) expressed as YYYY-MM-DD.
627 The number of cycles of interval length for which billing should occur
628 (inclusive of 'trial periods' if the processor supports recurring billing
629 at more than one rate)
633 =head2 test_transaction()
635 Most processors provide a test mode, where submitted transactions will
636 not actually be charged or added to your batch, calling this function
637 with a true argument will turn that mode on if the processor supports
638 it, or generate a fatal error if the processor does not support a test
639 mode (which is probably better than accidentally making real charges).
643 Providing a true argument to this module will turn on address
644 verification (if the processor supports it).
646 =head1 TRANSACTION SUBMISSION METHOD
650 Submit the transaction to the processor for completion.
652 If there is a gateway communication error or other "meta" , the submit method
653 will throw a fatal exception. You can catch this with eval {} if you would
654 like to treat gateway co
656 =head1 TRANSACTION RESULT METHODS
660 Returns true if the transaction was approved by the gateway, false if
661 it was submitted but not approved, or undef if it has not been
664 =head2 error_message()
666 If the transaction has been submitted but was not accepted, this
667 function will return the provided error message (if any) that the
670 =head2 failure_status()
672 If the transaction failed, it can optionally return a specific failure
673 status (normalized, not gateway-specific). Currently defined statuses
674 are: "expired", "nsf" (non-sufficient funds), "stolen", "pickup",
675 "blacklisted" and "declined" (card/transaction declines only, not
678 Note that not all processor modules support this, and that if supported,
679 it may not be set for all declines.
681 =head2 partial_auth_amount()
683 Amount of the partial authorization, if the processor supports them and the
684 partial_auth flag was passed to indicate they should be processed.
686 =head2 authorization()
688 If the transaction has been submitted and accepted, this function will
689 provide you with the authorization code that the processor returned.
690 Store this if you would like to run inquiries or refunds on the transaction
693 =head2 order_number()
695 The unique order number for the transaction generated by the gateway. Store
696 this if you would like to run inquiries or refunds on the transaction later.
700 If supported by your gateway, a card_token can be used in a subsequent
701 transaction to refer to a card number.
705 Retrieve or change the fraud score from any Business::FraudDetect plugin
707 =head2 fraud_transaction_id()
709 Retrieve or change the transaction id from any Business::FraudDetect plugin
711 =head2 response_code()
713 =head2 response_headers()
715 =head2 response_page()
717 These three fields are set by some processors (especially those which use
718 HTTPS) when the transaction fails at the communication level rather than
721 response_code is the HTTP response code and message, i.e.
722 '500 Internal Server Error'.
724 response_headers is a hash reference of the response headers
726 response_page is the raw content.
730 Returns the precise result code that the processor returned, these are
731 normally one letter codes that don't mean much unless you understand
732 the protocol they speak, you probably don't need this, but it's there
737 =head2 cvv2_response()
739 =head1 MISCELLANEOUS INTERNAL METHODS
741 =head2 transaction_type()
743 Retrieve the transaction type (the 'type' argument to contents()).
744 Generally only used internally, but provided in case it is useful.
748 Retrieve or change the processor submission server address (CHANGE AT
753 Retrieve or change the processor submission port (CHANGE AT YOUR OWN
758 Retrieve or change the processor submission path (CHANGE AT YOUR OWN
761 =head1 HELPER METHODS FOR GATEWAY MODULE AUTHORS
763 =head2 build_subs( @sub_names )
765 Build setter/getter subroutines for new return values.
767 =head2 get_fields( @fields )
769 Get the named fields if they are defined.
771 =head2 remap_fields( %map )
773 Remap field content (and stuff it back into content).
775 =head2 required_fields( @fields )
777 Croaks if any of the required fields are not present.
781 =head2 silly_bool( $value )
783 Returns 0 if the value starts with y, Y, t or T.
784 Returns 1 if the value starts with n, N, f or F.
785 Otherwise returns the value itself.
787 Use this for handling boolean content like tax_exempt.
793 Jason Kohles, email@jasonkohles.com
797 Ivan Kohler <ivan-business-onlinepayment@420.am>
799 Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
803 Copyright (c) 1999-2004 Jason Kohles
804 Copyright (c) 2004 Ivan Kohler
805 Copyright (c) 2007-2015 Freeside Internet Services, Inc.
809 This program is free software; you can redistribute it and/or modify it under
810 the same terms as Perl itself.
814 Homepage: http://perl.business/onlinepayment
816 Development: http://perl.business/onlinepayment/ng.html
820 Please direct current development questions, patches, etc. to the mailing list:
821 http://420.am/cgi-bin/mailman/listinfo/bop-devel/
825 The code is available from our public git repository:
827 git clone git://git.freeside.biz/Business-OnlinePayment.git
831 http://freeside.biz/gitweb/?p=Business-OnlinePayment.git
833 http://freeside.biz/gitlist/Business-OnlinePayment.git
835 Many (but by no means all!) processor plugins are also available in the same
838 http://freeside.biz/gitweb/
840 http://freeside.biz/gitlist/
844 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
845 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
846 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
850 http://perl.business/onlinepayment
852 For verification of credit card checksums, see L<Business::CreditCard>.