1 package Business::OnlinePayment;
11 $VERSION = eval $VERSION; # modperlstyle: convert the string into a number
14 authorization => undef,
15 error_message => undef,
16 failure_status => undef,
17 fraud_detect => undef,
19 maximum_risk => undef,
25 server_response => undef,
26 test_transaction => undef,
27 transaction_type => undef,
32 my($class,$processor,%data) = @_;
34 Carp::croak("unspecified processor") unless $processor;
36 my $subclass = "${class}::$processor";
37 if(!defined(&$subclass)) {
39 Carp::croak("unknown processor $processor ($@)") if $@;
42 my $self = bless {processor => $processor}, $subclass;
43 $self->build_subs(keys %fields);
45 if($self->can("set_defaults")) {
46 $self->set_defaults();
51 my $value = $data{$_};
53 $self->build_subs($key);
59 no warnings 'redefine';
60 my $submit = qualify_to_ref('submit', $subclass);
61 $self->{_child_submit} = \&$submit;
62 *{"${subclass}::submit"} = sub {
73 my ($self, $risk_transaction) = @_;
75 my %parent_content = $self->content();
76 $parent_content{action} = 'Fraud Detect';
77 $risk_transaction->content( %parent_content );
78 $risk_transaction->submit();
79 if ($risk_transaction->is_success()) {
80 if ( $risk_transaction->fraud_score <= $self->maximum_fraud_score()) {
81 $self->{_child_submit}->($self);
84 $self->error_message('Excessive risk from risk management');
87 $self->error_message('Error in risk detection stage: ' . $risk_transaction->error_message);
94 my $fraud_detection = $self->fraud_detect();
96 # early return if user does not want optional risk mgt
97 return $self->{_child_submit}->($self,@_) unless $fraud_detection && length $fraud_detection;
99 # Search for an appropriate FD module
100 foreach my $subclass ( q(Business::OnlinePayment::) . $fraud_detection,
101 q(Business::FraudDetect::) . $fraud_detection) {
103 if (!defined(&$subclass)) {
104 eval "use $subclass";
106 Carp::croak("serious problem loading fraud_detection module ($@)") unless
107 $@ =~ m/^Can\'t locate/;
109 my $risk_tx = bless ( { processor => $fraud_detection } , $subclass );
110 $risk_tx->build_subs(keys %fields);
111 if ($risk_tx->can('set_defaults')) {
112 $risk_tx->set_defaults();
114 $risk_tx->_glean_parameters_from_parent($self);
115 return $self->_risk_detect($risk_tx);
122 my($self,%params) = @_;
125 if($params{'type'}) { $self->transaction_type($params{'type'}); }
126 %{$self->{'_content'}} = %params;
128 return exists $self->{'_content'} ? %{$self->{'_content'}} : ();
131 sub required_fields {
132 my($self,@fields) = @_;
135 my %content = $self->content();
137 push(@missing, $_) unless exists $content{$_};
140 Carp::croak("missing required field(s): " . join(", ", @missing) . "\n")
145 my($self, @fields) = @_;
147 my %content = $self->content();
150 #foreach(@fields) { $new{$_} = $content{$_}; }
152 map { $_ => $content{$_} } grep defined $content{$_}, @fields;
158 my %content = $self->content();
159 foreach( keys %map ) {
160 $content{$map{$_}} = $content{$_};
162 $self->content(%content);
168 Carp::croak("Processor subclass did not override submit function");
174 my %content = $self->content();
176 foreach(sort keys %content) {
177 $dump .= "$_ = $content{$_}\n";
182 # didnt use AUTOLOAD because Net::SSLeay::AUTOLOAD passes right to
183 # AutoLoader::AUTOLOAD, instead of passing up the chain
188 next if($self->can($_));
189 eval "sub $_ { my \$self = shift; if(\@_) { \$self->{$_} = shift; } return \$self->{$_}; }";
199 Business::OnlinePayment - Perl extension for online payment processing
203 use Business::OnlinePayment;
205 my $transaction = new Business::OnlinePayment($processor, %processor_info);
206 $transaction->content(
209 card_number => '1234123412341238',
210 expiration => '0100',
211 name => 'John Q Doe',
213 $transaction->submit();
215 if($transaction->is_success()) {
216 print "Card processed successfully: ".$transaction->authorization()."\n";
218 print "Card was rejected: ".$transaction->error_message()."\n";
223 Business::OnlinePayment is a generic module for processing payments
224 through online credit card processors, electronic cash systems, etc.
226 =head1 METHODS AND FUNCTIONS
228 =head2 new($processor, %processor_options);
230 Create a new Business::OnlinePayment object, $processor is required,
231 and defines the online processor to use. If necessary, processor
232 options can be specified, currently supported options are 'Server',
233 'Port', and 'Path', which specify how to find the online processor
234 (https://server:port/path), but individual processor modules should
235 supply reasonable defaults for this information, override the defaults
236 only if absolutely necessary (especially path), as the processor
237 module was probably written with a specific target script in mind.
239 =head2 content(%content);
241 The information necessary for the transaction, this tends to vary a
242 little depending on the processor, so we have chosen to use a system
243 which defines specific fields in the frontend which get mapped to the
244 correct fields in the backend. The currently defined fields are:
250 Transaction type, supported types are:
251 Visa, MasterCard, American Express, Discover, Check (not all
252 processors support all these transaction types).
256 Your login name to use for authentication to the online processor.
260 Your password to use for authentication to the online processor.
264 What to do with the transaction (currently available are: Normal
265 Authorization, Authorization Only, Credit, Post Authorization)
269 A description of the transaction (used by some processors to send
270 information to the client, normally not a required field).
274 The amount of the transaction, most processors don't want dollar signs
275 and the like, just a floating point number.
277 =item * invoice_number
279 An invoice number, for your use and not normally required, many
280 processors require this field to be a numeric only field.
284 A customer identifier, again not normally required.
288 The customers name, your processor may not require this.
292 The customers address (your processor may not require this unless you
293 are requiring AVS Verification).
297 The customers city (your processor may not require this unless you are
298 requiring AVS Verification).
302 The customers state (your processor may not require this unless you
303 are requiring AVS Verification).
307 The customers zip code (your processor may not require this unless you
308 are requiring AVS Verification).
316 Customer's phone number.
320 Customer's fax number.
324 Customer's email address.
328 Credit card number (obviously not required for non-credit card
333 Credit card expiration (obviously not required for non-credit card
336 =item * account_number
338 Bank account number for electronic checks or electronic funds transfer.
342 Bank's routing code for electronic checks or electronic funds transfer.
346 Bank's name for electronic checks or electronic funds transfer.
352 Submit the transaction to the processor for completion
356 Returns true if the transaction was submitted successfully, false if
357 it failed (or undef if it has not been submitted yet).
359 =head2 failure_status();
361 If the transaction failed, it can optionally return a specific
362 failure status (normalized, not gateway-specific). Currently defined
363 statuses are: "expired", "nsf" (non-sufficient funds), "stolen",
364 "pickup", "blacklisted" and "declined" (card/transaction declines
365 only, not other errors).
367 Note that (as of Aug 2006) this is only supported by some of the
368 newest processor modules, and that, even if supported, a failure
369 status is an entirely optional field that is only set for specific
372 =head2 result_code();
374 Returns the precise result code that the processor returned, these are
375 normally one letter codes that don't mean much unless you understand
376 the protocol they speak, you probably don't need this, but it's there
379 =head2 test_transaction();
381 Most processors provide a test mode, where submitted transactions will
382 not actually be charged or added to your batch, calling this function
383 with a true argument will turn that mode on if the processor supports
384 it, or generate a fatal error if the processor does not support a test
385 mode (which is probably better than accidentally making real charges).
387 =head2 require_avs();
389 Providing a true argument to this module will turn on address
390 verification (if the processor supports it).
392 =head2 transaction_type();
394 Retrieve the transaction type (the 'type' argument to contents();).
395 Generally only used internally, but provided in case it is useful.
397 =head2 error_message();
399 If the transaction has been submitted but was not accepted, this
400 function will return the provided error message (if any) that the
403 =head2 authorization();
405 If the transaction has been submitted and accepted, this function will
406 provide you with the authorization code that the processor returned.
410 Retrieve or change the processor submission server address (CHANGE AT
415 Retrieve or change the processor submission port (CHANGE AT YOUR OWN RISK).
419 Retrieve or change the processor submission path (CHANGE AT YOUR OWN RISK).
423 Jason Kohles, email@jasonkohles.com
425 (v3 rewrite) Ivan Kohler <ivan-business-onlinepayment@420.am>
427 Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
431 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
432 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
433 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
437 http://420.am/business-onlinepayment/
439 For verification of credit card checksums, see L<Business::CreditCard>.