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_09';
  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 Recurring Authorization, Modify Recurring Authorization,
 283 Cancel Recurring Authorization)
 284
 285 =item * description
 286
 287 A description of the transaction (used by some processors to send
 288 information to the client, normally not a required field).
 289
 290 =item * amount
 291
 292 The amount of the transaction, most processors don't want dollar signs
 293 and the like, just a floating point number.
 294
 295 =item * invoice_number
 296
 297 An invoice number, for your use and not normally required, many
 298 processors require this field to be a numeric only field.
 299
 300 =back
 301
 302 =head3 CUSTOMER INFO FIELDS
 303
 304 =over 4
 305
 306 =item * customer_id
 307
 308 A customer identifier, again not normally required.
 309
 310 =item * name
 311
 312 The customer's name, your processor may not require this.
 313
 314 =item * first_name
 315
 316 =item * last_name
 317
 318 The customer's first and last name as separate fields.
 319
 320 =item * company
 321
 322 The customer's company name, not normally required.
 323
 324 =item * address
 325
 326 The customer's address (your processor may not require this unless you
 327 are requiring AVS Verification).
 328
 329 =item * city
 330
 331 The customer's city (your processor may not require this unless you
 332 are requiring AVS Verification).
 333
 334 =item * state
 335
 336 The customer's state (your processor may not require this unless you
 337 are requiring AVS Verification).
 338
 339 =item * zip
 340
 341 The customer's zip code (your processor may not require this unless
 342 you are requiring AVS Verification).
 343
 344 =item * country
 345
 346 Customer's country.
 347
 348 =item * ship_first_name
 349
 350 =item * ship_last_name
 351
 352 =item * ship_company
 353
 354 =item * ship_address
 355
 356 =item * ship_city
 357
 358 =item * ship_state
 359
 360 =item * ship_zip
 361
 362 =item * ship_country
 363
 364 These shipping address fields may be accepted by your processor.
 365 Refer to the description for the corresponding non-ship field for
 366 general information on each field.
 367
 368 =item * phone
 369
 370 Customer's phone number.
 371
 372 =item * fax
 373
 374 Customer's fax number.
 375
 376 =item * email
 377
 378 Customer's email address.
 379
 380 =item * customer_ip
 381
 382 IP Address from which the transaction originated.
 383
 384 =back
 385
 386 =head3 CREDIT CARD FIELDS
 387
 388 =over 4
 389
 390 =item * card_number
 391
 392 Credit card number.
 393
 394 =item * cvv2
 395
 396 CVV2 number (also called CVC2 or CID) is a three- or four-digit
 397 security code used to reduce credit card fraud.
 398
 399 =item * expiration
 400
 401 Credit card expiration.
 402
 403 =item * track1
 404
 405 Track 1 on the magnetic stripe (Card present only)
 406
 407 =item * track2
 408
 409 Track 2 on the magnetic stripe (Card present only)
 410
 411 =item * recurring billing
 412
 413 Recurring billing flag
 414
 415 =back
 416
 417 =head3 ELECTRONIC CHECK FIELDS
 418
 419 =over 4
 420
 421 =item * account_number
 422
 423 Bank account number for electronic checks or electronic funds
 424 transfer.
 425
 426 =item * routing_code
 427
 428 Bank's routing code for electronic checks or electronic funds
 429 transfer.
 430
 431 =item * account_type
 432
 433 Account type for electronic checks or electronic funds transfer.  Can be
 434 (case-insensitive): B<Personal Checking>, B<Personal Savings>,
 435 B<Business Checking> or B<Business Savings>.
 436
 437 =item * account_name
 438
 439 Account holder's name for electronic checks or electronic funds
 440 transfer.
 441
 442 =item * bank_name
 443
 444 Bank's name for electronic checks or electronic funds transfer.
 445
 446 =item * check_type
 447
 448 Check type for electronic checks or electronic funds transfer.
 449
 450 =item * customer_org
 451
 452 Customer organization type.
 453
 454 =item * customer_ssn
 455
 456 Customer's social security number.  Typically only required for
 457 electronic checks or electronic funds transfer.
 458
 459 =item * license_num
 460
 461 Customer's driver's license number.  Typically only required for
 462 electronic checks or electronic funds transfer.
 463
 464 =item * license_dob
 465
 466 Customer's date of birth.  Typically only required for electronic
 467 checks or electronic funds transfer.
 468
 469 =back
 470
 471 =head3 RECURRING BILLING FIELDS
 472
 473 =over 4
 474
 475 =item * interval
 476
 477 Interval expresses the amount of time between billings: digits, whitespace
 478 and units (currently "days" or "months" in either singular or plural form).
 479
 480 =item * start
 481
 482 The date of the first transaction (used for processors which allow delayed
 483 start) expressed as YYYY-MM-DD.
 484
 485 =item * periods
 486
 487 The number of cycles of interval length for which billing should occur
 488 (inclusive of 'trial periods' if the processor supports recurring billing
 489 at more than one rate)
 490
 491 =back
 492
 493 =head2 submit();
 494
 495 Submit the transaction to the processor for completion
 496
 497 =head2 is_success();
 498
 499 Returns true if the transaction was submitted successfully, false if
 500 it failed (or undef if it has not been submitted yet).
 501
 502 =head2 failure_status();
 503
 504 If the transaction failed, it can optionally return a specific failure
 505 status (normalized, not gateway-specific).  Currently defined statuses
 506 are: "expired", "nsf" (non-sufficient funds), "stolen", "pickup",
 507 "blacklisted" and "declined" (card/transaction declines only, not
 508 other errors).
 509
 510 Note that (as of Aug 2006) this is only supported by some of the
 511 newest processor modules, and that, even if supported, a failure
 512 status is an entirely optional field that is only set for specific
 513 kinds of failures.
 514
 515 =head2 result_code();
 516
 517 Returns the precise result code that the processor returned, these are
 518 normally one letter codes that don't mean much unless you understand
 519 the protocol they speak, you probably don't need this, but it's there
 520 just in case.
 521
 522 =head2 test_transaction();
 523
 524 Most processors provide a test mode, where submitted transactions will
 525 not actually be charged or added to your batch, calling this function
 526 with a true argument will turn that mode on if the processor supports
 527 it, or generate a fatal error if the processor does not support a test
 528 mode (which is probably better than accidentally making real charges).
 529
 530 =head2 require_avs();
 531
 532 Providing a true argument to this module will turn on address
 533 verification (if the processor supports it).
 534
 535 =head2 transaction_type();
 536
 537 Retrieve the transaction type (the 'type' argument to contents()).
 538 Generally only used internally, but provided in case it is useful.
 539
 540 =head2 error_message();
 541
 542 If the transaction has been submitted but was not accepted, this
 543 function will return the provided error message (if any) that the
 544 processor returned.
 545
 546 =head2 authorization();
 547
 548 If the transaction has been submitted and accepted, this function will
 549 provide you with the authorization code that the processor returned.
 550
 551 =head2 server();
 552
 553 Retrieve or change the processor submission server address (CHANGE AT
 554 YOUR OWN RISK).
 555
 556 =head2 port();
 557
 558 Retrieve or change the processor submission port (CHANGE AT YOUR OWN
 559 RISK).
 560
 561 =head2 path();
 562
 563 Retrieve or change the processor submission path (CHANGE AT YOUR OWN
 564 RISK).
 565
 566 =head2 fraud_score();
 567
 568 Retrieve or change the fraud score from any Business::FraudDetect plugin
 569
 570 =head2 fraud_transaction_id();
 571
 572 Retrieve or change the transaction id from any Business::FraudDetect plugin
 573
 574 =head1 AUTHORS
 575
 576 Jason Kohles, email@jasonkohles.com
 577
 578 (v3 rewrite) Ivan Kohler <ivan-business-onlinepayment@420.am>
 579
 580 Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
 581
 582 =head1 MAILING LIST
 583
 584 Please direct current development questions, patches, etc. to the mailing list:
 585 http://420.am/cgi-bin/mailman/listinfo/bop-devel/
 586
 587 =head1 DISCLAIMER
 588
 589 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
 590 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 591 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 592
 593 =head1 SEE ALSO
 594
 595 http://420.am/business-onlinepayment/
 596
 597 For verification of credit card checksums, see L<Business::CreditCard>.
 598
 599 =cut