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 __PACKAGE__->build_subs(@methods);
48 ( my $gw = $class ) =~ s/^Business::OnlinePayment:://;
50 'info_compat' => '0.00',
51 'gateway_name' => $gw,
52 'module_notes' => "Module does not yet provide info.",
56 #allow classes to declare info in a flexible way, but return normalized info
58 'supported_types' => sub {
59 my( $class, $v ) = @_;
60 my $types = ref($v) ? $v : defined($v) ? [ $v ] : [];
61 $types = { map { $_=>1 } @$types } if ref($types) eq 'ARRAY';
64 'supported_actions' => sub {
65 my( $class, $v ) = @_;
66 return %$v if ref($v) eq 'HASH';
67 $v = [ $v ] unless ref($v);
68 my $types = $class->info('supported_types') || {};
69 ( map { $_ => $v } keys %$types );
74 my $class = shift; #class or object
75 my $info = $class->_info;
78 exists($_info_handler{$key})
79 ? &{ $_info_handler{$key} }( $class, $info->{$key} )
82 wantarray ? ( keys %$info ) : [ keys %$info ];
87 my($class,$processor,%data) = @_;
89 croak("unspecified processor") unless $processor;
91 my $subclass = "${class}::$processor";
93 croak("unknown processor $processor ($@)") if $@;
95 my $self = bless {processor => $processor}, $subclass;
97 if($self->can("set_defaults")) {
98 $self->set_defaults(%data);
101 foreach(keys %data) {
103 my $value = $data{$_};
105 $self->build_subs($key);
109 # "wrap" submit with _pre_submit only once
110 unless ( $Presubmit_Added{$subclass} ) {
111 my $real_submit = $subclass->can('submit');
113 no warnings 'redefine';
116 *{"${subclass}::submit"} = sub {
118 return unless $self->_pre_submit(@_);
119 return $real_submit->($self, @_);
127 my ($self, $risk_transaction) = @_;
129 my %parent_content = $self->content();
130 $parent_content{action} = 'Fraud Detect';
131 $risk_transaction->content( %parent_content );
132 $risk_transaction->submit();
133 if ($risk_transaction->is_success()) {
134 $self->fraud_score( $risk_transaction->fraud_score );
135 $self->fraud_transaction_id( $risk_transaction->fraud_transaction_id );
136 if ( $risk_transaction->fraud_score <= $self->maximum_fraud_score()) {
139 $self->error_message('Excessive risk from risk management');
142 $self->error_message('Error in risk detection stage: ' . $risk_transaction->error_message);
144 $self->is_success(0);
148 my @Fraud_Class_Path = qw(Business::OnlinePayment Business::FraudDetect);
152 my $fraud_detection = $self->fraud_detect();
154 # early return if user does not want optional risk mgt
155 return 1 unless $fraud_detection;
157 # Search for an appropriate FD module
158 foreach my $fraud_class ( @Fraud_Class_Path ) {
159 my $subclass = $fraud_class . "::" . $fraud_detection;
160 eval "use $subclass ()";
162 croak("error loading fraud_detection module ($@)")
163 unless ( $@ =~ m/^Can\'t locate/ );
165 my $risk_tx = bless( { processor => $fraud_detection }, $subclass );
166 if ($risk_tx->can('set_defaults')) {
167 $risk_tx->set_defaults();
169 $risk_tx->_glean_parameters_from_parent($self);
170 return $self->_risk_detect($risk_tx);
173 croak("Unable to locate fraud_detection module $fraud_detection"
174 . " in \@INC under Fraud_Class_Path (\@Fraud_Class_Path"
175 . " contains: @Fraud_Class_Path) (\@INC contains: @INC)");
179 my($self,%params) = @_;
182 if($params{'type'}) { $self->transaction_type($params{'type'}); }
183 %{$self->{'_content'}} = %params;
185 return exists $self->{'_content'} ? %{$self->{'_content'}} : ();
188 sub required_fields {
189 my($self,@fields) = @_;
192 my %content = $self->content();
194 push(@missing, $_) unless exists $content{$_};
197 croak("missing required field(s): " . join(", ", @missing) . "\n")
202 my($self, @fields) = @_;
204 my %content = $self->content();
207 #foreach(@fields) { $new{$_} = $content{$_}; }
209 map { $_ => $content{$_} } grep defined $content{$_}, @fields;
215 my %content = $self->content();
216 foreach( keys %map ) {
217 $content{$map{$_}} = $content{$_};
219 $self->content(%content);
225 croak("Processor subclass did not override submit function");
231 my %content = $self->content();
233 foreach(sort keys %content) {
234 $dump .= "$_ = $content{$_}\n";
239 # didnt use AUTOLOAD because Net::SSLeay::AUTOLOAD passes right to
240 # AutoLoader::AUTOLOAD, instead of passing up the chain
245 next if($self->can($_));
246 eval "sub $_ { my \$self = shift; if(\@_) { \$self->{$_} = shift; } return \$self->{$_}; }";
253 my( $self, $value ) = @_;
254 return 1 if $value =~ /^[yt]/i;
255 return 0 if $value =~ /^[fn]/i;
256 #return 1 if $value == 1;
257 #return 0 if $value == 0;
267 Business::OnlinePayment - Perl extension for online payment processing
271 use Business::OnlinePayment;
273 my $transaction = new Business::OnlinePayment($processor, %processor_info);
274 $transaction->content(
277 card_number => '1234123412341238',
278 expiration => '06/15',
279 name => 'John Q Doe',
282 eval { $transaction->submit(); };
286 print "$processor error: $@\n";
290 if ( $transaction->is_success() ) {
291 print "Card processed successfully: ". $transaction->authorization()."\n";
293 print "Card was rejected: ". $transaction->error_message(). "\n";
300 Business::OnlinePayment is a generic module for processing payments
301 through online credit card processors, electronic cash systems, etc.
305 =head2 new($processor, %processor_options)
307 Create a new Business::OnlinePayment object, $processor is required,
308 and defines the online processor to use. If necessary, processor
309 options can be specified, currently supported options are 'Server',
310 'Port', and 'Path', which specify how to find the online processor
311 (https://server:port/path), but individual processor modules should
312 supply reasonable defaults for this information, override the defaults
313 only if absolutely necessary (especially path), as the processor
314 module was probably written with a specific target script in mind.
316 =head1 TRANSACTION SETUP METHODS
318 =head2 content(%content)
320 The information necessary for the transaction, this tends to vary a
321 little depending on the processor, so we have chosen to use a system
322 which defines specific fields in the frontend which get mapped to the
323 correct fields in the backend. The currently defined fields are:
325 =head3 PROCESSOR FIELDS
331 Your login name to use for authentication to the online processor.
335 Your password to use for authentication to the online processor.
339 =head3 REQUIRED TRANSACTION FIELDS
345 Transaction type, supported types are: CC (credit card), ECHECK
346 (electronic check) and LEC (phone bill billing). Deprecated types
347 are: Visa, MasterCard, American Express, Discover, Check. Not all
348 processors support all transaction types.
352 What action being taken by this transaction. Currently available are:
356 =item Normal Authorization
358 =item Authorization Only
360 =item Post Authorization
362 =item Reverse Authorization
368 =item Recurring Authorization
370 =item Modify Recurring Authorization
372 =item Cancel Recurring Authorization
378 The amount of the transaction. No dollar signs or currency identifiers,
379 just a whole or floating point number (i.e. 26, 26.1 or 26.13).
383 =head3 OPTIONAL TRANSACTION FIELDS
389 Set true to accept a partial authorization. If this flag is not set, a partial
390 authorization will be immediately reversed or voided.
394 A description of the transaction (used by some processors to send
395 information to the client, normally not a required field).
399 An invoice number, for your use and not normally required, many
400 processors require this field to be a numeric only field.
404 Purchase order number (normally not required).
408 Tax amount (portion of amount field, not added to it).
412 Freight amount (portion of amount field, not added to it).
416 Duty amount (portion of amount field, not added to it).
420 Tax exempt flag (i.e. TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0).
424 Currency, specified as an ISO 4217 three-letter code, such as USD, CAD, EUR,
425 AUD, DKK, GBP, JPY, NZD, etc.
429 If you are prepared to handle partial authorizations
430 (see L<partial_auth_amount()|/"partial_auth_amount()">
431 in L<TRANSACTION RESULT FIELDS|/"TRANSACTION RESULT FIELDS">),
432 pass a true value in this field to enable them.
436 =head3 CUSTOMER INFO FIELDS
442 A customer identifier, again not normally required.
446 The customer's name, your processor may not require this.
452 The customer's first and last name as separate fields.
456 The customer's company name, not normally required.
460 The customer's address (your processor may not require this unless you
461 are requiring AVS Verification).
465 The customer's city (your processor may not require this unless you
466 are requiring AVS Verification).
470 The customer's state (your processor may not require this unless you
471 are requiring AVS Verification).
475 The customer's zip code (your processor may not require this unless
476 you are requiring AVS Verification).
482 =item ship_first_name
498 These shipping address fields may be accepted by your processor.
499 Refer to the description for the corresponding non-ship field for
500 general information on each field.
504 Customer's phone number.
508 Customer's fax number.
512 Customer's email address.
516 IP Address from which the transaction originated.
520 =head3 CREDIT CARD FIELDS
530 Credit card expiration, MM/YY.
534 CVV2 number (also called CVC2 or CID) is a three- or four-digit
535 security code used to reduce credit card fraud.
539 If supported by your gateway, you can pass a card_token instead of a
540 card_number and expiration.
546 #Some card_token schemes implement a challenge/response handshake. In those
547 #cases, this field is used for the response. In most cases the handshake
548 #it taken care of by the gateway module.
552 Track 1 on the magnetic stripe (Card present only)
556 Track 2 on the magnetic stripe (Card present only)
558 =item recurring_billing
560 Recurring billing flag
564 =head3 ELECTRONIC CHECK FIELDS
578 Account type. Can be (case-insensitive): B<Personal Checking>,
579 B<Personal Savings>, B<Business Checking> or B<Business Savings>.
583 Account holder's name.
603 Customer organization type.
607 Customer's social security number.
611 Customer's driver's license number.
615 Customer's date of birth.
619 =head3 RECURRING BILLING FIELDS
625 Interval expresses the amount of time between billings: digits, whitespace
626 and units (currently "days" or "months" in either singular or plural form).
630 The date of the first transaction (used for processors which allow delayed
631 start) expressed as YYYY-MM-DD.
635 The number of cycles of interval length for which billing should occur
636 (inclusive of 'trial periods' if the processor supports recurring billing
637 at more than one rate)
641 =head2 test_transaction()
643 Most processors provide a test mode, where submitted transactions will
644 not actually be charged or added to your batch, calling this function
645 with a true argument will turn that mode on if the processor supports
646 it, or generate a fatal error if the processor does not support a test
647 mode (which is probably better than accidentally making real charges).
651 Providing a true argument to this module will turn on address
652 verification (if the processor supports it).
654 =head1 TRANSACTION SUBMISSION METHOD
658 Submit the transaction to the processor for completion.
660 If there is a gateway communication error or other "meta" , the submit method
661 will throw a fatal exception. You can catch this with eval {} if you would
662 like to treat gateway co
664 =head1 TRANSACTION RESULT METHODS
668 Returns true if the transaction was approved by the gateway, false if
669 it was submitted but not approved, or undef if it has not been
672 =head2 partial_auth_amount()
674 If this transaction was a partial authorization (i.e. successful, but less than
675 the requested amount was processed), then the amount processed is returned in
678 (When is_success is true but this field is empty or 0, that indicates a normal
679 full authorization for the entire requested amount.)
681 =head2 error_message()
683 If the transaction has been submitted but was not accepted, this
684 function will return the provided error message (if any) that the
687 =head2 failure_status()
689 If the transaction failed, it can optionally return a specific failure
690 status (normalized, not gateway-specific). Currently defined statuses
691 are: "expired", "nsf" (non-sufficient funds), "stolen", "pickup",
692 "blacklisted" and "declined" (card/transaction declines only, not
695 Note that not all processor modules support this, and that if supported,
696 it may not be set for all declines.
698 =head2 partial_auth_amount()
700 Amount of the partial authorization, if the processor supports them and the
701 partial_auth flag was passed to indicate they should be processed.
703 =head2 authorization()
705 If the transaction has been submitted and accepted, this function will
706 provide you with the authorization code that the processor returned.
707 Store this if you would like to run inquiries or refunds on the transaction
710 =head2 order_number()
712 The unique order number for the transaction generated by the gateway. Store
713 this if you would like to run inquiries or refunds on the transaction later.
717 If supported by your gateway, a card_token can be used in a subsequent
718 transaction to refer to a card number.
722 Retrieve or change the fraud score from any Business::FraudDetect plugin
724 =head2 fraud_transaction_id()
726 Retrieve or change the transaction id from any Business::FraudDetect plugin
728 =head2 response_code()
730 =head2 response_headers()
732 =head2 response_page()
734 These three fields are set by some processors (especially those which use
735 HTTPS) when the transaction fails at the communication level rather than
738 response_code is the HTTP response code and message, i.e.
739 '500 Internal Server Error'.
741 response_headers is a hash reference of the response headers
743 response_page is the raw content.
747 Returns the precise result code that the processor returned, these are
748 normally one letter codes that don't mean much unless you understand
749 the protocol they speak, you probably don't need this, but it's there
754 =head2 cvv2_response()
756 =head1 MISCELLANEOUS INTERNAL METHODS
758 =head2 transaction_type()
760 Retrieve the transaction type (the 'type' argument to contents()).
761 Generally only used internally, but provided in case it is useful.
765 Retrieve or change the processor submission server address (CHANGE AT
770 Retrieve or change the processor submission port (CHANGE AT YOUR OWN
775 Retrieve or change the processor submission path (CHANGE AT YOUR OWN
778 =head1 HELPER METHODS FOR GATEWAY MODULE AUTHORS
780 =head2 build_subs( @sub_names )
782 Build setter/getter subroutines for new return values.
784 =head2 get_fields( @fields )
786 Get the named fields if they are defined.
788 =head2 remap_fields( %map )
790 Remap field content (and stuff it back into content).
792 =head2 required_fields( @fields )
794 Croaks if any of the required fields are not present.
798 =head2 silly_bool( $value )
800 Returns 0 if the value starts with y, Y, t or T.
801 Returns 1 if the value starts with n, N, f or F.
802 Otherwise returns the value itself.
804 Use this for handling boolean content like tax_exempt.
810 Jason Kohles, email@jasonkohles.com
814 Ivan Kohler <ivan-business-onlinepayment@420.am>
816 Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
820 Copyright (c) 1999-2004 Jason Kohles
821 Copyright (c) 2004 Ivan Kohler
822 Copyright (c) 2007-2015 Freeside Internet Services, Inc.
826 This program is free software; you can redistribute it and/or modify it under
827 the same terms as Perl itself.
831 Homepage: http://perl.business/onlinepayment
833 Development: http://perl.business/onlinepayment/ng.html
837 Please direct current development questions, patches, etc. to the mailing list:
838 http://420.am/cgi-bin/mailman/listinfo/bop-devel/
842 The code is available from our public git repository:
844 git clone git://git.freeside.biz/Business-OnlinePayment.git
848 http://freeside.biz/gitweb/?p=Business-OnlinePayment.git
850 http://freeside.biz/gitlist/Business-OnlinePayment.git
852 Many (but by no means all!) processor plugins are also available in the same
855 http://freeside.biz/gitweb/
857 http://freeside.biz/gitlist/
861 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
862 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
863 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
867 http://perl.business/onlinepayment
869 For verification of credit card checksums, see L<Business::CreditCard>.