OnlinePayment.pm

   1 package Business::OnlinePayment;
   2
   3 use strict;
   4 use vars qw($VERSION);
   5 use Carp;
   6
   7 require 5.005;
   8
   9 $VERSION = '3.00_08';
  10 $VERSION = eval $VERSION; # modperlstyle: convert the string into a number
  11
  12 # Remember subclasses we have "wrapped" submit() with _pre_submit()
  13 my %Presubmit_Added = ();
  14
  15 my %fields = (
  16     authorization        => undef,
  17     error_message        => undef,
  18     failure_status       => undef,
  19     fraud_detect         => undef,
  20     is_success           => undef,
  21     maximum_risk         => undef,
  22     path                 => undef,
  23     port                 => undef,
  24     require_avs          => undef,
  25     result_code          => undef,
  26     server               => undef,
  27     server_response      => undef,
  28     test_transaction     => undef,
  29     transaction_type     => undef,
  30     fraud_score          => undef,
  31     fraud_transaction_id => undef,
  32 );
  33
  34 sub new {
  35     my($class,$processor,%data) = @_;
  36
  37     croak("unspecified processor") unless $processor;
  38
  39     my $subclass = "${class}::$processor";
  40     eval "use $subclass";
  41     croak("unknown processor $processor ($@)") if $@;
  42
  43     my $self = bless {processor => $processor}, $subclass;
  44     $self->build_subs(keys %fields);
  45
  46     if($self->can("set_defaults")) {
  47         $self->set_defaults(%data);
  48     }
  49
  50     foreach(keys %data) {
  51         my $key = lc($_);
  52         my $value = $data{$_};
  53         $key =~ s/^\-+//;
  54         $self->build_subs($key);
  55         $self->$key($value);
  56     }
  57
  58     # "wrap" submit with _pre_submit only once
  59     unless ( $Presubmit_Added{$subclass} ) {
  60         my $real_submit = $subclass->can('submit');
  61
  62         no warnings 'redefine';
  63         no strict 'refs';
  64
  65         *{"${subclass}::submit"} = sub {
  66             my $self = shift;
  67             return unless $self->_pre_submit(@_);
  68             return $real_submit->($self, @_);
  69         }
  70     }
  71
  72     return $self;
  73 }
  74
  75 sub _risk_detect {
  76     my ($self, $risk_transaction) = @_;
  77
  78     my %parent_content = $self->content();
  79     $parent_content{action} = 'Fraud Detect';
  80     $risk_transaction->content( %parent_content );
  81     $risk_transaction->submit();
  82     if ($risk_transaction->is_success()) {
  83          $self->fraud_score( $risk_transaction->fraud_score );
  84          $self->fraud_transaction_id( $risk_transaction->fraud_transaction_id );
  85         if ( $risk_transaction->fraud_score <= $self->maximum_fraud_score()) {
  86             return 1;
  87         } else {
  88             $self->error_message('Excessive risk from risk management');
  89         }
  90     } else {
  91         $self->error_message('Error in risk detection stage: ' .  $risk_transaction->error_message);
  92     }
  93     $self->is_success(0);
  94     return 0;
  95 }
  96
  97 my @Fraud_Class_Path = qw(Business::OnlinePayment Business::FraudDetect);
  98
  99 sub _pre_submit {
 100     my ($self) = @_;
 101     my $fraud_detection = $self->fraud_detect();
 102
 103     # early return if user does not want optional risk mgt
 104     return 1 unless $fraud_detection;
 105
 106     # Search for an appropriate FD module
 107     foreach my $fraud_class ( @Fraud_Class_Path ) {
 108         my $subclass = $fraud_class . "::" . $fraud_detection;
 109         eval "use $subclass ()";
 110         if ($@) {
 111             croak("error loading fraud_detection module ($@)")
 112               unless ( $@ =~ m/^Can\'t locate/ );
 113         } else {
 114             my $risk_tx = bless( { processor => $fraud_detection }, $subclass );
 115             $risk_tx->build_subs(keys %fields);
 116             if ($risk_tx->can('set_defaults')) {
 117                 $risk_tx->set_defaults();
 118             }
 119             $risk_tx->_glean_parameters_from_parent($self);
 120             return $self->_risk_detect($risk_tx);
 121         }
 122     }
 123     croak("Unable to locate fraud_detection module $fraud_detection"
 124                 . " in \@INC under Fraud_Class_Path (\@Fraud_Class_Path"
 125                 . " contains: @Fraud_Class_Path) (\@INC contains: @INC)");
 126 }
 127
 128 sub content {
 129     my($self,%params) = @_;
 130
 131     if(%params) {
 132         if($params{'type'}) { $self->transaction_type($params{'type'}); }
 133         %{$self->{'_content'}} = %params;
 134     }
 135     return exists $self->{'_content'} ? %{$self->{'_content'}} : ();
 136 }
 137
 138 sub required_fields {
 139     my($self,@fields) = @_;
 140
 141     my @missing;
 142     my %content = $self->content();
 143     foreach(@fields) {
 144         push(@missing, $_) unless exists $content{$_};
 145     }
 146
 147     croak("missing required field(s): " . join(", ", @missing) . "\n")
 148           if(@missing);
 149 }
 150
 151 sub get_fields {
 152     my($self, @fields) = @_;
 153
 154     my %content = $self->content();
 155
 156     #my %new = ();
 157     #foreach(@fields) { $new{$_} = $content{$_}; }
 158     #return %new;
 159     map { $_ => $content{$_} } grep defined $content{$_}, @fields;
 160 }
 161
 162 sub remap_fields {
 163     my($self,%map) = @_;
 164
 165     my %content = $self->content();
 166     foreach( keys %map ) {
 167         $content{$map{$_}} = $content{$_};
 168     }
 169     $self->content(%content);
 170 }
 171
 172 sub submit {
 173     my($self) = @_;
 174
 175     croak("Processor subclass did not override submit function");
 176 }
 177
 178 sub dump_contents {
 179     my($self) = @_;
 180
 181     my %content = $self->content();
 182     my $dump = "";
 183     foreach(sort keys %content) {
 184         $dump .= "$_ = $content{$_}\n";
 185     }
 186     return $dump;
 187 }
 188
 189 # didnt use AUTOLOAD because Net::SSLeay::AUTOLOAD passes right to
 190 # AutoLoader::AUTOLOAD, instead of passing up the chain
 191 sub build_subs {
 192     my $self = shift;
 193
 194     foreach(@_) {
 195         next if($self->can($_));
 196         eval "sub $_ { my \$self = shift; if(\@_) { \$self->{$_} = shift; } return \$self->{$_}; }";
 197     }
 198 }
 199
 200 1;
 201
 202 __END__
 203
 204 =head1 NAME
 205
 206 Business::OnlinePayment - Perl extension for online payment processing
 207
 208 =head1 SYNOPSIS
 209
 210   use Business::OnlinePayment;
 211
 212   my $transaction = new Business::OnlinePayment($processor, %processor_info);
 213   $transaction->content(
 214                         type        => 'Visa',
 215                         amount      => '49.95',
 216                         card_number => '1234123412341238',
 217                         expiration  => '0100',
 218                         name        => 'John Q Doe',
 219                        );
 220   $transaction->submit();
 221
 222   if($transaction->is_success()) {
 223     print "Card processed successfully: ", $transaction->authorization(), "\n";
 224   } else {
 225     print "Card was rejected: ", $transaction->error_message(), "\n";
 226   }
 227
 228 =head1 DESCRIPTION
 229
 230 Business::OnlinePayment is a generic module for processing payments
 231 through online credit card processors, electronic cash systems, etc.
 232
 233 =head1 METHODS AND FUNCTIONS
 234
 235 =head2 new($processor, %processor_options);
 236
 237 Create a new Business::OnlinePayment object, $processor is required,
 238 and defines the online processor to use.  If necessary, processor
 239 options can be specified, currently supported options are 'Server',
 240 'Port', and 'Path', which specify how to find the online processor
 241 (https://server:port/path), but individual processor modules should
 242 supply reasonable defaults for this information, override the defaults
 243 only if absolutely necessary (especially path), as the processor
 244 module was probably written with a specific target script in mind.
 245
 246 =head2 content(%content);
 247
 248 The information necessary for the transaction, this tends to vary a
 249 little depending on the processor, so we have chosen to use a system
 250 which defines specific fields in the frontend which get mapped to the
 251 correct fields in the backend.  The currently defined fields are:
 252
 253 =head3 PROCESSOR FIELDS
 254
 255 =over 4
 256
 257 =item * login
 258
 259 Your login name to use for authentication to the online processor.
 260
 261 =item * password
 262
 263 Your password to use for authentication to the online processor.
 264
 265 =back
 266
 267 =head3 GENERAL TRANSACTION FIELDS
 268
 269 =over 4
 270
 271 =item * type
 272
 273 Transaction type, supported types are: CC (credit card), ECHECK
 274 (electronic check) and LEC (phone bill billing).  Deprecated types
 275 are: Visa, MasterCard, American Express, Discover, Check (not all
 276 processors support all these transaction types).
 277
 278 =item * action
 279
 280 What to do with the transaction (currently available are: Normal
 281 Authorization, Authorization Only, Credit, Post Authorization)
 282
 283 =item * description
 284
 285 A description of the transaction (used by some processors to send
 286 information to the client, normally not a required field).
 287
 288 =item * amount
 289
 290 The amount of the transaction, most processors don't want dollar signs
 291 and the like, just a floating point number.
 292
 293 =item * invoice_number
 294
 295 An invoice number, for your use and not normally required, many
 296 processors require this field to be a numeric only field.
 297
 298 =back
 299
 300 =head3 CUSTOMER INFO FIELDS
 301
 302 =over 4
 303
 304 =item * customer_id
 305
 306 A customer identifier, again not normally required.
 307
 308 =item * name
 309
 310 The customer's name, your processor may not require this.
 311
 312 =item * first_name
 313
 314 =item * last_name
 315
 316 The customer's first and last name as separate fields.
 317
 318 =item * company
 319
 320 The customer's company name, not normally required.
 321
 322 =item * address
 323
 324 The customer's address (your processor may not require this unless you
 325 are requiring AVS Verification).
 326
 327 =item * city
 328
 329 The customer's city (your processor may not require this unless you
 330 are requiring AVS Verification).
 331
 332 =item * state
 333
 334 The customer's state (your processor may not require this unless you
 335 are requiring AVS Verification).
 336
 337 =item * zip
 338
 339 The customer's zip code (your processor may not require this unless
 340 you are requiring AVS Verification).
 341
 342 =item * country
 343
 344 Customer's country.
 345
 346 =item * ship_first_name
 347
 348 =item * ship_last_name
 349
 350 =item * ship_company
 351
 352 =item * ship_address
 353
 354 =item * ship_city
 355
 356 =item * ship_state
 357
 358 =item * ship_zip
 359
 360 =item * ship_country
 361
 362 These shipping address fields may be accepted by your processor.
 363 Refer to the description for the corresponding non-ship field for
 364 general information on each field.
 365
 366 =item * phone
 367
 368 Customer's phone number.
 369
 370 =item * fax
 371
 372 Customer's fax number.
 373
 374 =item * email
 375
 376 Customer's email address.
 377
 378 =item * customer_ip
 379
 380 IP Address from which the transaction originated.
 381
 382 =back
 383
 384 =head3 CREDIT CARD FIELDS
 385
 386 =over 4
 387
 388 =item * card_number
 389
 390 Credit card number (obviously not required for non-credit card
 391 transactions).
 392
 393 =item * cvv2
 394
 395 CVV2 number (also called CVC2 or CID) is a three- or four-digit
 396 security code used to reduce credit card fraud.
 397
 398 =item * expiration
 399
 400 Credit card expiration (obviously not required for non-credit card
 401 transactions).
 402
 403 =item * recurring billing
 404
 405 Recurring billing flag
 406
 407 =back
 408
 409 =head3 ELECTRONIC CHECK FIELDS
 410
 411 =over 4
 412
 413 =item * account_number
 414
 415 Bank account number for electronic checks or electronic funds
 416 transfer.
 417
 418 =item * routing_code
 419
 420 Bank's routing code for electronic checks or electronic funds
 421 transfer.
 422
 423 =item * account_type
 424
 425 Account type for electronic checks or electronic funds transfer.
 426
 427 =item * account_name
 428
 429 Account holder's name for electronic checks or electronic funds
 430 transfer.
 431
 432 =item * bank_name
 433
 434 Bank's name for electronic checks or electronic funds transfer.
 435
 436 =item * check_type
 437
 438 Check type for electronic checks or electronic funds transfer.
 439
 440 =item * customer_org
 441
 442 Customer organization type.
 443
 444 =item * customer_ssn
 445
 446 Customer's social security number.  Typically only required for
 447 electronic checks or electronic funds transfer.
 448
 449 =item * license_num
 450
 451 Customer's driver's license number.  Typically only required for
 452 electronic checks or electronic funds transfer.
 453
 454 =item * license_dob
 455
 456 Customer's date of birth.  Typically only required for electronic
 457 checks or electronic funds transfer.
 458
 459 =back
 460
 461 =head2 submit();
 462
 463 Submit the transaction to the processor for completion
 464
 465 =head2 is_success();
 466
 467 Returns true if the transaction was submitted successfully, false if
 468 it failed (or undef if it has not been submitted yet).
 469
 470 =head2 failure_status();
 471
 472 If the transaction failed, it can optionally return a specific failure
 473 status (normalized, not gateway-specific).  Currently defined statuses
 474 are: "expired", "nsf" (non-sufficient funds), "stolen", "pickup",
 475 "blacklisted" and "declined" (card/transaction declines only, not
 476 other errors).
 477
 478 Note that (as of Aug 2006) this is only supported by some of the
 479 newest processor modules, and that, even if supported, a failure
 480 status is an entirely optional field that is only set for specific
 481 kinds of failures.
 482
 483 =head2 result_code();
 484
 485 Returns the precise result code that the processor returned, these are
 486 normally one letter codes that don't mean much unless you understand
 487 the protocol they speak, you probably don't need this, but it's there
 488 just in case.
 489
 490 =head2 test_transaction();
 491
 492 Most processors provide a test mode, where submitted transactions will
 493 not actually be charged or added to your batch, calling this function
 494 with a true argument will turn that mode on if the processor supports
 495 it, or generate a fatal error if the processor does not support a test
 496 mode (which is probably better than accidentally making real charges).
 497
 498 =head2 require_avs();
 499
 500 Providing a true argument to this module will turn on address
 501 verification (if the processor supports it).
 502
 503 =head2 transaction_type();
 504
 505 Retrieve the transaction type (the 'type' argument to contents()).
 506 Generally only used internally, but provided in case it is useful.
 507
 508 =head2 error_message();
 509
 510 If the transaction has been submitted but was not accepted, this
 511 function will return the provided error message (if any) that the
 512 processor returned.
 513
 514 =head2 authorization();
 515
 516 If the transaction has been submitted and accepted, this function will
 517 provide you with the authorization code that the processor returned.
 518
 519 =head2 server();
 520
 521 Retrieve or change the processor submission server address (CHANGE AT
 522 YOUR OWN RISK).
 523
 524 =head2 port();
 525
 526 Retrieve or change the processor submission port (CHANGE AT YOUR OWN
 527 RISK).
 528
 529 =head2 path();
 530
 531 Retrieve or change the processor submission path (CHANGE AT YOUR OWN
 532 RISK).
 533
 534 =head2 fraud_score();
 535
 536 Retrieve or change the fraud score from any Business::FraudDetect plugin
 537
 538 =head2 fraud_transaction_id();
 539
 540 Retrieve or change the transaction id from any Business::FraudDetect plugin
 541
 542 =head1 AUTHORS
 543
 544 Jason Kohles, email@jasonkohles.com
 545
 546 (v3 rewrite) Ivan Kohler <ivan-business-onlinepayment@420.am>
 547
 548 Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
 549
 550 =head1 MAILING LIST
 551
 552 Please direct current development questions, patches, etc. to the mailing list:
 553 http://420.am/cgi-bin/mailman/listinfo/bop-devel/
 554
 555 =head1 DISCLAIMER
 556
 557 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
 558 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 559 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 560
 561 =head1 SEE ALSO
 562
 563 http://420.am/business-onlinepayment/
 564
 565 For verification of credit card checksums, see L<Business::CreditCard>.
 566
 567 =cut