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 = ();
43 ( my $gw = $class ) =~ s/^Business::OnlinePayment:://;
45 'info_compat' => '0.00',
46 'gateway_name' => $gw,
47 'module_notes' => "Module does not yet provide info.",
51 #allow classes to declare info in a flexible way, but return normalized info
53 'supported_types' => sub {
54 my( $class, $v ) = @_;
55 my $types = ref($v) ? $v : defined($v) ? [ $v ] : [];
56 $types = { map { $_=>1 } @$types } if ref($types) eq 'ARRAY';
59 'supported_actions' => sub {
60 my( $class, $v ) = @_;
61 return %$v if ref($v) eq 'HASH';
62 $v = [ $v ] unless ref($v);
63 my $types = $class->info('supported_types') || {};
64 ( map { $_ => $v } keys %$types );
69 my $class = shift; #class or object
70 my $info = $class->_info;
73 exists($_info_handler{$key})
74 ? &{ $_info_handler{$key} }( $class, $info->{$key} )
77 wantarray ? ( keys %$info ) : [ keys %$info ];
82 my($class,$processor,%data) = @_;
84 croak("unspecified processor") unless $processor;
86 my $subclass = "${class}::$processor";
88 croak("unknown processor $processor ($@)") if $@;
90 my $self = bless {processor => $processor}, $subclass;
91 $self->build_subs(@methods);
93 if($self->can("set_defaults")) {
94 $self->set_defaults(%data);
99 my $value = $data{$_};
101 $self->build_subs($key);
105 # "wrap" submit with _pre_submit only once
106 unless ( $Presubmit_Added{$subclass} ) {
107 my $real_submit = $subclass->can('submit');
109 no warnings 'redefine';
112 *{"${subclass}::submit"} = sub {
114 return unless $self->_pre_submit(@_);
115 return $real_submit->($self, @_);
123 my ($self, $risk_transaction) = @_;
125 my %parent_content = $self->content();
126 $parent_content{action} = 'Fraud Detect';
127 $risk_transaction->content( %parent_content );
128 $risk_transaction->submit();
129 if ($risk_transaction->is_success()) {
130 $self->fraud_score( $risk_transaction->fraud_score );
131 $self->fraud_transaction_id( $risk_transaction->fraud_transaction_id );
132 if ( $risk_transaction->fraud_score <= $self->maximum_fraud_score()) {
135 $self->error_message('Excessive risk from risk management');
138 $self->error_message('Error in risk detection stage: ' . $risk_transaction->error_message);
140 $self->is_success(0);
144 my @Fraud_Class_Path = qw(Business::OnlinePayment Business::FraudDetect);
148 my $fraud_detection = $self->fraud_detect();
150 # early return if user does not want optional risk mgt
151 return 1 unless $fraud_detection;
153 # Search for an appropriate FD module
154 foreach my $fraud_class ( @Fraud_Class_Path ) {
155 my $subclass = $fraud_class . "::" . $fraud_detection;
156 eval "use $subclass ()";
158 croak("error loading fraud_detection module ($@)")
159 unless ( $@ =~ m/^Can\'t locate/ );
161 my $risk_tx = bless( { processor => $fraud_detection }, $subclass );
162 $risk_tx->build_subs(@methods);
163 if ($risk_tx->can('set_defaults')) {
164 $risk_tx->set_defaults();
166 $risk_tx->_glean_parameters_from_parent($self);
167 return $self->_risk_detect($risk_tx);
170 croak("Unable to locate fraud_detection module $fraud_detection"
171 . " in \@INC under Fraud_Class_Path (\@Fraud_Class_Path"
172 . " contains: @Fraud_Class_Path) (\@INC contains: @INC)");
176 my($self,%params) = @_;
179 if($params{'type'}) { $self->transaction_type($params{'type'}); }
180 %{$self->{'_content'}} = %params;
182 return exists $self->{'_content'} ? %{$self->{'_content'}} : ();
185 sub required_fields {
186 my($self,@fields) = @_;
189 my %content = $self->content();
191 push(@missing, $_) unless exists $content{$_};
194 croak("missing required field(s): " . join(", ", @missing) . "\n")
199 my($self, @fields) = @_;
201 my %content = $self->content();
204 #foreach(@fields) { $new{$_} = $content{$_}; }
206 map { $_ => $content{$_} } grep defined $content{$_}, @fields;
212 my %content = $self->content();
213 foreach( keys %map ) {
214 $content{$map{$_}} = $content{$_};
216 $self->content(%content);
222 croak("Processor subclass did not override submit function");
228 my %content = $self->content();
230 foreach(sort keys %content) {
231 $dump .= "$_ = $content{$_}\n";
236 # didnt use AUTOLOAD because Net::SSLeay::AUTOLOAD passes right to
237 # AutoLoader::AUTOLOAD, instead of passing up the chain
242 next if($self->can($_));
243 eval "sub $_ { my \$self = shift; if(\@_) { \$self->{$_} = shift; } return \$self->{$_}; }";
250 my( $self, $value ) = @_;
251 return 1 if $value =~ /^[yt]/i;
252 return 0 if $value =~ /^[fn]/i;
253 #return 1 if $value == 1;
254 #return 0 if $value == 0;
264 Business::OnlinePayment - Perl extension for online payment processing
268 use Business::OnlinePayment;
270 my $transaction = new Business::OnlinePayment($processor, %processor_info);
271 $transaction->content(
274 card_number => '1234123412341238',
275 expiration => '06/15',
276 name => 'John Q Doe',
279 eval { $transaction->submit(); };
283 print "$processor error: $@\n";
287 if ( $transaction->is_success() ) {
288 print "Card processed successfully: ". $transaction->authorization()."\n";
290 print "Card was rejected: ". $transaction->error_message(). "\n";
297 Business::OnlinePayment is a generic module for processing payments
298 through online credit card processors, electronic cash systems, etc.
302 =head2 new($processor, %processor_options)
304 Create a new Business::OnlinePayment object, $processor is required,
305 and defines the online processor to use. If necessary, processor
306 options can be specified, currently supported options are 'Server',
307 'Port', and 'Path', which specify how to find the online processor
308 (https://server:port/path), but individual processor modules should
309 supply reasonable defaults for this information, override the defaults
310 only if absolutely necessary (especially path), as the processor
311 module was probably written with a specific target script in mind.
313 =head1 TRANSACTION SETUP METHODS
315 =head2 content(%content)
317 The information necessary for the transaction, this tends to vary a
318 little depending on the processor, so we have chosen to use a system
319 which defines specific fields in the frontend which get mapped to the
320 correct fields in the backend. The currently defined fields are:
322 =head3 PROCESSOR FIELDS
328 Your login name to use for authentication to the online processor.
332 Your password to use for authentication to the online processor.
336 =head3 REQUIRED TRANSACTION FIELDS
342 Transaction type, supported types are: CC (credit card), ECHECK
343 (electronic check) and LEC (phone bill billing). Deprecated types
344 are: Visa, MasterCard, American Express, Discover, Check. Not all
345 processors support all transaction types.
349 What action being taken by this transaction. Currently available are:
353 =item Normal Authorization
355 =item Authorization Only
357 =item Post Authorization
359 =item Reverse Authorization
365 =item Recurring Authorization
367 =item Modify Recurring Authorization
369 =item Cancel Recurring Authorization
375 The amount of the transaction. No dollar signs or currency identifiers,
376 just a whole or floating point number (i.e. 26, 26.1 or 26.13).
380 =head3 OPTIONAL TRANSACTION FIELDS
386 A description of the transaction (used by some processors to send
387 information to the client, normally not a required field).
391 An invoice number, for your use and not normally required, many
392 processors require this field to be a numeric only field.
396 Purchase order number (normally not required).
400 Tax amount (portion of amount field, not added to it).
404 Freight amount (portion of amount field, not added to it).
408 Duty amount (portion of amount field, not added to it).
412 Tax exempt flag (i.e. TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0).
416 Currency, specified as an ISO 4217 three-letter code, such as USD, CAD, EUR,
417 AUD, DKK, GBP, JPY, NZD, etc.
421 =head3 CUSTOMER INFO FIELDS
427 A customer identifier, again not normally required.
431 The customer's name, your processor may not require this.
437 The customer's first and last name as separate fields.
441 The customer's company name, not normally required.
445 The customer's address (your processor may not require this unless you
446 are requiring AVS Verification).
450 The customer's city (your processor may not require this unless you
451 are requiring AVS Verification).
455 The customer's state (your processor may not require this unless you
456 are requiring AVS Verification).
460 The customer's zip code (your processor may not require this unless
461 you are requiring AVS Verification).
467 =item ship_first_name
483 These shipping address fields may be accepted by your processor.
484 Refer to the description for the corresponding non-ship field for
485 general information on each field.
489 Customer's phone number.
493 Customer's fax number.
497 Customer's email address.
501 IP Address from which the transaction originated.
505 =head3 CREDIT CARD FIELDS
515 Credit card expiration, MM/YY.
519 CVV2 number (also called CVC2 or CID) is a three- or four-digit
520 security code used to reduce credit card fraud.
524 If supported by your gateway, you can pass a card_token instead of a
525 card_number and expiration.
531 #Some card_token schemes implement a challenge/response handshake. In those
532 #cases, this field is used for the response. In most cases the handshake
533 #it taken care of by the gateway module.
537 Track 1 on the magnetic stripe (Card present only)
541 Track 2 on the magnetic stripe (Card present only)
543 =item recurring_billing
545 Recurring billing flag
549 =head3 ELECTRONIC CHECK FIELDS
563 Account type. Can be (case-insensitive): B<Personal Checking>,
564 B<Personal Savings>, B<Business Checking> or B<Business Savings>.
568 Account holder's name.
588 Customer organization type.
592 Customer's social security number.
596 Customer's driver's license number.
600 Customer's date of birth.
604 =head3 RECURRING BILLING FIELDS
610 Interval expresses the amount of time between billings: digits, whitespace
611 and units (currently "days" or "months" in either singular or plural form).
615 The date of the first transaction (used for processors which allow delayed
616 start) expressed as YYYY-MM-DD.
620 The number of cycles of interval length for which billing should occur
621 (inclusive of 'trial periods' if the processor supports recurring billing
622 at more than one rate)
626 =head2 test_transaction()
628 Most processors provide a test mode, where submitted transactions will
629 not actually be charged or added to your batch, calling this function
630 with a true argument will turn that mode on if the processor supports
631 it, or generate a fatal error if the processor does not support a test
632 mode (which is probably better than accidentally making real charges).
636 Providing a true argument to this module will turn on address
637 verification (if the processor supports it).
639 =head1 TRANSACTION SUBMISSION METHOD
643 Submit the transaction to the processor for completion.
645 If there is a gateway communication error or other "meta" , the submit method
646 will throw a fatal exception. You can catch this with eval {} if you would
647 like to treat gateway co
649 =head1 TRANSACTION RESULT METHODS
653 Returns true if the transaction was approved by the gateway, false if
654 it was submitted but not approved, or undef if it has not been
657 =head2 error_message()
659 If the transaction has been submitted but was not accepted, this
660 function will return the provided error message (if any) that the
663 =head2 failure_status()
665 If the transaction failed, it can optionally return a specific failure
666 status (normalized, not gateway-specific). Currently defined statuses
667 are: "expired", "nsf" (non-sufficient funds), "stolen", "pickup",
668 "blacklisted" and "declined" (card/transaction declines only, not
671 Note that not all processor modules support this, and that if supported,
672 it may not be set for all declines.
674 =head2 authorization()
676 If the transaction has been submitted and accepted, this function will
677 provide you with the authorization code that the processor returned.
678 Store this if you would like to run inquiries or refunds on the transaction
681 =head2 order_number()
683 The unique order number for the transaction generated by the gateway. Store
684 this if you would like to run inquiries or refunds on the transaction later.
688 If supported by your gateway, a card_token can be used in a subsequent
689 transaction to refer to a card number.
693 Retrieve or change the fraud score from any Business::FraudDetect plugin
695 =head2 fraud_transaction_id()
697 Retrieve or change the transaction id from any Business::FraudDetect plugin
699 =head2 response_code()
701 =head2 response_headers()
703 =head2 response_page()
705 These three fields are set by some processors (especially those which use
706 HTTPS) when the transaction fails at the communication level rather than
709 response_code is the HTTP response code and message, i.e.
710 '500 Internal Server Error'.
712 response_headers is a hash reference of the response headers
714 response_page is the raw content.
718 Returns the precise result code that the processor returned, these are
719 normally one letter codes that don't mean much unless you understand
720 the protocol they speak, you probably don't need this, but it's there
725 =head2 cvv2_response()
727 =head1 MISCELLANEOUS INTERNAL METHODS
729 =head2 transaction_type()
731 Retrieve the transaction type (the 'type' argument to contents()).
732 Generally only used internally, but provided in case it is useful.
736 Retrieve or change the processor submission server address (CHANGE AT
741 Retrieve or change the processor submission port (CHANGE AT YOUR OWN
746 Retrieve or change the processor submission path (CHANGE AT YOUR OWN
749 =head1 HELPER METHODS FOR GATEWAY MODULE AUTHORS
751 =head2 build_subs( @sub_names )
753 Build setter/getter subroutines for new return values.
755 =head2 get_fields( @fields )
757 Get the named fields if they are defined.
759 =head2 remap_fields( %map )
761 Remap field content (and stuff it back into content).
763 =head2 required_fields( @fields )
765 Croaks if any of the required fields are not present.
769 =head2 silly_bool( $value )
771 Returns 0 if the value starts with y, Y, t or T.
772 Returns 1 if the value starts with n, N, f or F.
773 Otherwise returns the value itself.
775 Use this for handling boolean content like tax_exempt.
781 Jason Kohles, email@jasonkohles.com
785 Ivan Kohler <ivan-business-onlinepayment@420.am>
787 Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
791 Copyright (c) 1999-2004 Jason Kohles
792 Copyright (c) 2004 Ivan Kohler
793 Copyright (c) 2007-2014 Freeside Internet Services, Inc.
797 This program is free software; you can redistribute it and/or modify it under
798 the same terms as Perl itself.
802 Homepage: http://420.am/business-onlinepayment/
804 Development: http://420.am/business-onlinepayment/ng.html
808 Please direct current development questions, patches, etc. to the mailing list:
809 http://420.am/cgi-bin/mailman/listinfo/bop-devel/
813 The code is available from our public git repository:
815 git clone git://git.freeside.biz/Business-OnlinePayment.git
819 http://freeside.biz/gitweb/?p=Business-OnlinePayment.git
821 Many (but by no means all!) processor plugins are also available in the same
824 http://freeside.biz/gitweb/
828 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
829 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
830 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
834 http://420.am/business-onlinepayment/
836 For verification of credit card checksums, see L<Business::CreditCard>.