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 (obviously not required for non-credit card
 393 transactions).
 394
 395 =item * cvv2
 396
 397 CVV2 number (also called CVC2 or CID) is a three- or four-digit
 398 security code used to reduce credit card fraud.
 399
 400 =item * expiration
 401
 402 Credit card expiration (obviously not required for non-credit card
 403 transactions).
 404
 405 =item * recurring billing
 406
 407 Recurring billing flag
 408
 409 =back
 410
 411 =head3 ELECTRONIC CHECK FIELDS
 412
 413 =over 4
 414
 415 =item * account_number
 416
 417 Bank account number for electronic checks or electronic funds
 418 transfer.
 419
 420 =item * routing_code
 421
 422 Bank's routing code for electronic checks or electronic funds
 423 transfer.
 424
 425 =item * account_type
 426
 427 Account type for electronic checks or electronic funds transfer.  Can be
 428 (case-insensitive): B<Personal Checking>, B<Personal Savings>,
 429 B<Business Checking> or B<Business Savings>.
 430
 431 =item * account_name
 432
 433 Account holder's name for electronic checks or electronic funds
 434 transfer.
 435
 436 =item * bank_name
 437
 438 Bank's name for electronic checks or electronic funds transfer.
 439
 440 =item * check_type
 441
 442 Check type for electronic checks or electronic funds transfer.
 443
 444 =item * customer_org
 445
 446 Customer organization type.
 447
 448 =item * customer_ssn
 449
 450 Customer's social security number.  Typically only required for
 451 electronic checks or electronic funds transfer.
 452
 453 =item * license_num
 454
 455 Customer's driver's license number.  Typically only required for
 456 electronic checks or electronic funds transfer.
 457
 458 =item * license_dob
 459
 460 Customer's date of birth.  Typically only required for electronic
 461 checks or electronic funds transfer.
 462
 463 =back
 464
 465 =head3 RECURRING BILLING FIELDS
 466
 467 =over 4
 468
 469 =item * interval
 470
 471 Interval expresses the amount of time between billings: digits, whitespace
 472 and units (currently "days" or "months" in either singular or plural form).
 473
 474 =item * start
 475
 476 The date of the first transaction (used for processors which allow delayed
 477 start) expressed as YYYY-MM-DD.
 478
 479 =item * periods
 480
 481 The number of cycles of interval length for which billing should occur
 482 (inclusive of 'trial periods' if the processor supports recurring billing
 483 at more than one rate)
 484
 485 =back
 486
 487 =head2 submit();
 488
 489 Submit the transaction to the processor for completion
 490
 491 =head2 is_success();
 492
 493 Returns true if the transaction was submitted successfully, false if
 494 it failed (or undef if it has not been submitted yet).
 495
 496 =head2 failure_status();
 497
 498 If the transaction failed, it can optionally return a specific failure
 499 status (normalized, not gateway-specific).  Currently defined statuses
 500 are: "expired", "nsf" (non-sufficient funds), "stolen", "pickup",
 501 "blacklisted" and "declined" (card/transaction declines only, not
 502 other errors).
 503
 504 Note that (as of Aug 2006) this is only supported by some of the
 505 newest processor modules, and that, even if supported, a failure
 506 status is an entirely optional field that is only set for specific
 507 kinds of failures.
 508
 509 =head2 result_code();
 510
 511 Returns the precise result code that the processor returned, these are
 512 normally one letter codes that don't mean much unless you understand
 513 the protocol they speak, you probably don't need this, but it's there
 514 just in case.
 515
 516 =head2 test_transaction();
 517
 518 Most processors provide a test mode, where submitted transactions will
 519 not actually be charged or added to your batch, calling this function
 520 with a true argument will turn that mode on if the processor supports
 521 it, or generate a fatal error if the processor does not support a test
 522 mode (which is probably better than accidentally making real charges).
 523
 524 =head2 require_avs();
 525
 526 Providing a true argument to this module will turn on address
 527 verification (if the processor supports it).
 528
 529 =head2 transaction_type();
 530
 531 Retrieve the transaction type (the 'type' argument to contents()).
 532 Generally only used internally, but provided in case it is useful.
 533
 534 =head2 error_message();
 535
 536 If the transaction has been submitted but was not accepted, this
 537 function will return the provided error message (if any) that the
 538 processor returned.
 539
 540 =head2 authorization();
 541
 542 If the transaction has been submitted and accepted, this function will
 543 provide you with the authorization code that the processor returned.
 544
 545 =head2 server();
 546
 547 Retrieve or change the processor submission server address (CHANGE AT
 548 YOUR OWN RISK).
 549
 550 =head2 port();
 551
 552 Retrieve or change the processor submission port (CHANGE AT YOUR OWN
 553 RISK).
 554
 555 =head2 path();
 556
 557 Retrieve or change the processor submission path (CHANGE AT YOUR OWN
 558 RISK).
 559
 560 =head2 fraud_score();
 561
 562 Retrieve or change the fraud score from any Business::FraudDetect plugin
 563
 564 =head2 fraud_transaction_id();
 565
 566 Retrieve or change the transaction id from any Business::FraudDetect plugin
 567
 568 =head1 AUTHORS
 569
 570 Jason Kohles, email@jasonkohles.com
 571
 572 (v3 rewrite) Ivan Kohler <ivan-business-onlinepayment@420.am>
 573
 574 Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
 575
 576 =head1 MAILING LIST
 577
 578 Please direct current development questions, patches, etc. to the mailing list:
 579 http://420.am/cgi-bin/mailman/listinfo/bop-devel/
 580
 581 =head1 DISCLAIMER
 582
 583 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
 584 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 585 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 586
 587 =head1 SEE ALSO
 588
 589 http://420.am/business-onlinepayment/
 590
 591 For verification of credit card checksums, see L<Business::CreditCard>.
 592
 593 =cut