OnlinePayment.pm

   1 package Business::OnlinePayment;
   2
   3 use strict;
   4 use vars qw($VERSION %_info_handler);
   5 use Carp;
   6
   7 require 5.005;
   8
   9 $VERSION = '3.05_01';
  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 @methods = qw(
  16     authorization
  17     order_number
  18     error_message
  19     failure_status
  20     fraud_detect
  21     is_success
  22     partial_auth_amount
  23     maximum_risk
  24     path
  25     port
  26     require_avs
  27     result_code
  28     server
  29     server_response
  30     test_transaction
  31     transaction_type
  32     fraud_score
  33     fraud_transaction_id
  34     response_code
  35     response_header
  36     response_page
  37     avs_code
  38     cvv2_response
  39     txn_date
  40 );
  41
  42 __PACKAGE__->build_subs(@methods);
  43
  44 #fallback
  45 sub _info {
  46   my $class = shift;
  47   ( my $gw = $class ) =~ s/^Business::OnlinePayment:://;
  48   {
  49     'info_compat'    => '0.00',
  50     'gateway_name'   => $gw,
  51     'module_notes'   => "Module does not yet provide info.",
  52   };
  53 }
  54
  55 #allow classes to declare info in a flexible way, but return normalized info
  56 %_info_handler = (
  57   'supported_types'   => sub {
  58     my( $class, $v ) = @_;
  59     my $types = ref($v) ? $v : defined($v) ? [ $v ] : [];
  60     $types = { map { $_=>1 } @$types } if ref($types) eq 'ARRAY';
  61     $types;
  62   },
  63   'supported_actions' => sub {
  64     my( $class, $v ) = @_;
  65     return %$v if ref($v) eq 'HASH';
  66     $v = [ $v ] unless ref($v);
  67     my $types = $class->info('supported_types') || {};
  68     ( map { $_ => $v } keys %$types );
  69   },
  70 );
  71
  72 sub info {
  73   my $class = shift; #class or object
  74   my $info = $class->_info;
  75   if ( @_ ) {
  76     my $key = shift;
  77     exists($_info_handler{$key})
  78       ? &{ $_info_handler{$key} }( $class, $info->{$key} )
  79       : $info->{$key};
  80   } else {
  81     wantarray ? ( keys %$info ) : [ keys %$info ];
  82   }
  83 }
  84
  85 sub new {
  86     my($class,$processor,%data) = @_;
  87
  88     croak("unspecified processor") unless $processor;
  89
  90     my $subclass = "${class}::$processor";
  91     eval "use $subclass";
  92     croak("unknown processor $processor ($@)") if $@;
  93
  94     my $self = bless {processor => $processor}, $subclass;
  95
  96     if($self->can("set_defaults")) {
  97         $self->set_defaults(%data);
  98     }
  99
 100     foreach(keys %data) {
 101         my $key = lc($_);
 102         my $value = $data{$_};
 103         $key =~ s/^\-+//;
 104         $self->build_subs($key);
 105         $self->$key($value);
 106     }
 107
 108     # "wrap" submit with _pre_submit only once
 109     unless ( $Presubmit_Added{$subclass} ) {
 110         my $real_submit = $subclass->can('submit');
 111
 112         no warnings 'redefine';
 113         no strict 'refs';
 114
 115         *{"${subclass}::submit"} = sub {
 116             my $self = shift;
 117             return unless $self->_pre_submit(@_);
 118             return $real_submit->($self, @_);
 119         }
 120     }
 121
 122     return $self;
 123 }
 124
 125 sub _risk_detect {
 126     my ($self, $risk_transaction) = @_;
 127
 128     my %parent_content = $self->content();
 129     $parent_content{action} = 'Fraud Detect';
 130     $risk_transaction->content( %parent_content );
 131     $risk_transaction->submit();
 132     if ($risk_transaction->is_success()) {
 133          $self->fraud_score( $risk_transaction->fraud_score );
 134          $self->fraud_transaction_id( $risk_transaction->fraud_transaction_id );
 135         if ( $risk_transaction->fraud_score <= $self->maximum_fraud_score()) {
 136             return 1;
 137         } else {
 138             $self->error_message('Excessive risk from risk management');
 139         }
 140     } else {
 141         $self->error_message('Error in risk detection stage: ' .  $risk_transaction->error_message);
 142     }
 143     $self->is_success(0);
 144     return 0;
 145 }
 146
 147 my @Fraud_Class_Path = qw(Business::OnlinePayment Business::FraudDetect);
 148
 149 sub _pre_submit {
 150     my ($self) = @_;
 151     my $fraud_detection = $self->fraud_detect();
 152
 153     # early return if user does not want optional risk mgt
 154     return 1 unless $fraud_detection;
 155
 156     # Search for an appropriate FD module
 157     foreach my $fraud_class ( @Fraud_Class_Path ) {
 158         my $subclass = $fraud_class . "::" . $fraud_detection;
 159         eval "use $subclass ()";
 160         if ($@) {
 161             croak("error loading fraud_detection module ($@)")
 162               unless ( $@ =~ m/^Can\'t locate/ );
 163         } else {
 164             my $risk_tx = bless( { processor => $fraud_detection }, $subclass );
 165             if ($risk_tx->can('set_defaults')) {
 166                 $risk_tx->set_defaults();
 167             }
 168             $risk_tx->_glean_parameters_from_parent($self);
 169             return $self->_risk_detect($risk_tx);
 170         }
 171     }
 172     croak("Unable to locate fraud_detection module $fraud_detection"
 173                 . " in \@INC under Fraud_Class_Path (\@Fraud_Class_Path"
 174                 . " contains: @Fraud_Class_Path) (\@INC contains: @INC)");
 175 }
 176
 177 sub content {
 178     my($self,%params) = @_;
 179
 180     if(%params) {
 181         if($params{'type'}) { $self->transaction_type($params{'type'}); }
 182         %{$self->{'_content'}} = %params;
 183     }
 184     return exists $self->{'_content'} ? %{$self->{'_content'}} : ();
 185 }
 186
 187 sub required_fields {
 188     my($self,@fields) = @_;
 189
 190     my @missing;
 191     my %content = $self->content();
 192     foreach(@fields) {
 193         push(@missing, $_) unless exists $content{$_};
 194     }
 195
 196     croak("missing required field(s): " . join(", ", @missing) . "\n")
 197           if(@missing);
 198 }
 199
 200 sub get_fields {
 201     my($self, @fields) = @_;
 202
 203     my %content = $self->content();
 204
 205     #my %new = ();
 206     #foreach(@fields) { $new{$_} = $content{$_}; }
 207     #return %new;
 208     map { $_ => $content{$_} } grep defined $content{$_}, @fields;
 209 }
 210
 211 sub remap_fields {
 212     my($self,%map) = @_;
 213
 214     my %content = $self->content();
 215     foreach( keys %map ) {
 216         $content{$map{$_}} = $content{$_};
 217     }
 218     $self->content(%content);
 219 }
 220
 221 sub submit {
 222     my($self) = @_;
 223
 224     croak("Processor subclass did not override submit function");
 225 }
 226
 227 sub dump_contents {
 228     my($self) = @_;
 229
 230     my %content = $self->content();
 231     my $dump = "";
 232     foreach(sort keys %content) {
 233         $dump .= "$_ = $content{$_}\n";
 234     }
 235     return $dump;
 236 }
 237
 238 # didnt use AUTOLOAD because Net::SSLeay::AUTOLOAD passes right to
 239 # AutoLoader::AUTOLOAD, instead of passing up the chain
 240 sub build_subs {
 241     my $self = shift;
 242
 243     foreach(@_) {
 244         next if($self->can($_));
 245         eval "sub $_ { my \$self = shift; if(\@_) { \$self->{$_} = shift; } return \$self->{$_}; }";
 246     }
 247 }
 248
 249 #helper method
 250
 251 sub silly_bool {
 252   my( $self, $value ) = @_;
 253   return 1 if $value =~ /^[yt]/i;
 254   return 0 if $value =~ /^[fn]/i;
 255   #return 1 if $value == 1;
 256   #return 0 if $value == 0;
 257   $value; #die??
 258 }
 259
 260 1;
 261
 262 __END__
 263
 264 =head1 NAME
 265
 266 Business::OnlinePayment - Perl extension for online payment processing
 267
 268 =head1 SYNOPSIS
 269
 270   use Business::OnlinePayment;
 271
 272   my $transaction = new Business::OnlinePayment($processor, %processor_info);
 273   $transaction->content(
 274                         type        => 'Visa',
 275                         amount      => '49.95',
 276                         card_number => '1234123412341238',
 277                         expiration  => '06/15',
 278                         name        => 'John Q Doe',
 279                        );
 280
 281   eval { $transaction->submit(); };
 282
 283   if ( $@ ) {
 284
 285     print "$processor error: $@\n";
 286
 287   } else {
 288
 289     if ( $transaction->is_success() ) {
 290       print "Card processed successfully: ". $transaction->authorization()."\n";
 291     } else {
 292       print "Card was rejected: ". $transaction->error_message(). "\n";
 293     }
 294
 295   }
 296
 297 =head1 DESCRIPTION
 298
 299 Business::OnlinePayment is a generic module for processing payments
 300 through online credit card processors, electronic cash systems, etc.
 301
 302 =head1 CONSTRUCTOR
 303
 304 =head2 new($processor, %processor_options)
 305
 306 Create a new Business::OnlinePayment object, $processor is required,
 307 and defines the online processor to use.  If necessary, processor
 308 options can be specified, currently supported options are 'Server',
 309 'Port', and 'Path', which specify how to find the online processor
 310 (https://server:port/path), but individual processor modules should
 311 supply reasonable defaults for this information, override the defaults
 312 only if absolutely necessary (especially path), as the processor
 313 module was probably written with a specific target script in mind.
 314
 315 =head1 TRANSACTION SETUP METHODS
 316
 317 =head2 content(%content)
 318
 319 The information necessary for the transaction, this tends to vary a
 320 little depending on the processor, so we have chosen to use a system
 321 which defines specific fields in the frontend which get mapped to the
 322 correct fields in the backend.  The currently defined fields are:
 323
 324 =head3 PROCESSOR FIELDS
 325
 326 =over 4
 327
 328 =item login
 329
 330 Your login name to use for authentication to the online processor.
 331
 332 =item password
 333
 334 Your password to use for authentication to the online processor.
 335
 336 =back
 337
 338 =head3 REQUIRED TRANSACTION FIELDS
 339
 340 =over 4
 341
 342 =item type
 343
 344 Transaction type, supported types are: CC (credit card), ECHECK
 345 (electronic check) and LEC (phone bill billing).  Deprecated types
 346 are: Visa, MasterCard, American Express, Discover, Check.  Not all
 347 processors support all transaction types.
 348
 349 =item action
 350
 351 What action being taken by this transaction. Currently available are:
 352
 353 =over 8
 354
 355 =item Normal Authorization
 356
 357 =item Authorization Only
 358
 359 =item Post Authorization
 360
 361 =item Reverse Authorization
 362
 363 =item Void
 364
 365 =item Credit
 366
 367 =item Recurring Authorization
 368
 369 =item Modify Recurring Authorization
 370
 371 =item Cancel Recurring Authorization
 372
 373 =back
 374
 375 =item amount
 376
 377 The amount of the transaction.  No dollar signs or currency identifiers,
 378 just a whole or floating point number (i.e. 26, 26.1 or 26.13).
 379
 380 =back
 381
 382 =head3 OPTIONAL TRANSACTION FIELDS
 383
 384 =over 4
 385
 386 =item partial_auth
 387
 388 If you are prepared to handle partial authorizations
 389 (see L<partial_auth_amount()|/"partial_auth_amount()">
 390  in L<TRANSACTION RESULT FIELDS|/"TRANSACTION RESULT FIELDS">),
 391 pass a true value in this field to enable them.
 392
 393 If this flag is not set, a partial authorization will be immediately reversed
 394 or voided.
 395
 396 =item description
 397
 398 A description of the transaction (used by some processors to send
 399 information to the client, normally not a required field).
 400
 401 =item invoice_number
 402
 403 An invoice number, for your use and not normally required, many
 404 processors require this field to be a numeric only field.
 405
 406 =item po_number
 407
 408 Purchase order number (normally not required).
 409
 410 =item tax
 411
 412 Tax amount (portion of amount field, not added to it).
 413
 414 =item freight
 415
 416 Freight amount (portion of amount field, not added to it).
 417
 418 =item duty
 419
 420 Duty amount (portion of amount field, not added to it).
 421
 422 =item tax_exempt
 423
 424 Tax exempt flag (i.e. TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0).
 425
 426 =item currency
 427
 428 Currency, specified as an ISO 4217 three-letter code, such as USD, CAD, EUR,
 429 AUD, DKK, GBP, JPY, NZD, etc.
 430
 431 =back
 432
 433 =head3 CUSTOMER INFO FIELDS
 434
 435 =over 4
 436
 437 =item customer_id
 438
 439 A customer identifier, again not normally required.
 440
 441 =item name
 442
 443 The customer's name, your processor may not require this.
 444
 445 =item first_name
 446
 447 =item last_name
 448
 449 The customer's first and last name as separate fields.
 450
 451 =item company
 452
 453 The customer's company name, not normally required.
 454
 455 =item address
 456
 457 The customer's address (your processor may not require this unless you
 458 are requiring AVS Verification).
 459
 460 =item city
 461
 462 The customer's city (your processor may not require this unless you
 463 are requiring AVS Verification).
 464
 465 =item state
 466
 467 The customer's state (your processor may not require this unless you
 468 are requiring AVS Verification).
 469
 470 =item zip
 471
 472 The customer's zip code (your processor may not require this unless
 473 you are requiring AVS Verification).
 474
 475 =item country
 476
 477 Customer's country.
 478
 479 =item ship_first_name
 480
 481 =item ship_last_name
 482
 483 =item ship_company
 484
 485 =item ship_address
 486
 487 =item ship_city
 488
 489 =item ship_state
 490
 491 =item ship_zip
 492
 493 =item ship_country
 494
 495 These shipping address fields may be accepted by your processor.
 496 Refer to the description for the corresponding non-ship field for
 497 general information on each field.
 498
 499 =item phone
 500
 501 Customer's phone number.
 502
 503 =item fax
 504
 505 Customer's fax number.
 506
 507 =item email
 508
 509 Customer's email address.
 510
 511 =item customer_ip
 512
 513 IP Address from which the transaction originated.
 514
 515 =back
 516
 517 =head3 CREDIT CARD FIELDS
 518
 519 =over 4
 520
 521 =item card_number
 522
 523 Credit card number.
 524
 525 =item expiration
 526
 527 Credit card expiration, MM/YY.
 528
 529 =item cvv2
 530
 531 CVV2 number (also called CVC2 or CID) is a three- or four-digit
 532 security code used to reduce credit card fraud.
 533
 534 =item card_token
 535
 536 If supported by your gateway, you can pass a card_token instead of a
 537 card_number and expiration.
 538
 539 =cut
 540
 541 #=item card_response
 542 #
 543 #Some card_token schemes implement a challenge/response handshake.  In those
 544 #cases, this field is used for the response.  In most cases the handshake
 545 #it taken care of by the gateway module.
 546
 547 =item track1
 548
 549 Track 1 on the magnetic stripe (Card present only)
 550
 551 =item track2
 552
 553 Track 2 on the magnetic stripe (Card present only)
 554
 555 =item recurring_billing
 556
 557 Recurring billing flag
 558
 559 =back
 560
 561 =head3 ELECTRONIC CHECK FIELDS
 562
 563 =over 4
 564
 565 =item account_number
 566
 567 Bank account number
 568
 569 =item routing_code
 570
 571 Bank's routing code
 572
 573 =item account_type
 574
 575 Account type.  Can be (case-insensitive): B<Personal Checking>,
 576 B<Personal Savings>, B<Business Checking> or B<Business Savings>.
 577
 578 =item account_name
 579
 580 Account holder's name.
 581
 582 =item bank_name
 583
 584 Bank name.
 585
 586 =item bank_city
 587
 588 Bank city.
 589
 590 =item bank_state
 591
 592 Bank state.
 593
 594 =item check_type
 595
 596 Check type.
 597
 598 =item customer_org
 599
 600 Customer organization type.
 601
 602 =item customer_ssn
 603
 604 Customer's social security number.
 605
 606 =item license_num
 607
 608 Customer's driver's license number.
 609
 610 =item license_dob
 611
 612 Customer's date of birth.
 613
 614 =back
 615
 616 =head3 RECURRING BILLING FIELDS
 617
 618 =over 4
 619
 620 =item interval
 621
 622 Interval expresses the amount of time between billings: digits, whitespace
 623 and units (currently "days" or "months" in either singular or plural form).
 624
 625 =item start
 626
 627 The date of the first transaction (used for processors which allow delayed
 628 start) expressed as YYYY-MM-DD.
 629
 630 =item periods
 631
 632 The number of cycles of interval length for which billing should occur
 633 (inclusive of 'trial periods' if the processor supports recurring billing
 634 at more than one rate)
 635
 636 =back
 637
 638 =head2 test_transaction()
 639
 640 Most processors provide a test mode, where submitted transactions will
 641 not actually be charged or added to your batch, calling this function
 642 with a true argument will turn that mode on if the processor supports
 643 it, or generate a fatal error if the processor does not support a test
 644 mode (which is probably better than accidentally making real charges).
 645
 646 =head2 require_avs()
 647
 648 Providing a true argument to this module will turn on address
 649 verification (if the processor supports it).
 650
 651 =head1 TRANSACTION SUBMISSION METHOD
 652
 653 =head2 submit()
 654
 655 Submit the transaction to the processor for completion.
 656
 657 If there is a gateway communication error or other "meta" , the submit method
 658 will throw a fatal exception.  You can catch this with eval {} if you would
 659 like to treat gateway co
 660
 661 =head1 TRANSACTION RESULT METHODS
 662
 663 =head2 is_success()
 664
 665 Returns true if the transaction was approved by the gateway, false if
 666 it was submitted but not approved, or undef if it has not been
 667 submitted yet.
 668
 669 =head2 partial_auth_amount()
 670
 671 If this transaction was a partial authorization (i.e. successful, but less than
 672 the requested amount was processed), then the amount processed is returned in
 673 this field.
 674
 675 (When is_success is true but this field is empty or 0, that indicates a normal
 676 full authorization for the entire requested amount.)
 677
 678 =head2 error_message()
 679
 680 If the transaction has been submitted but was not accepted, this
 681 function will return the provided error message (if any) that the
 682 processor returned.
 683
 684 =head2 failure_status()
 685
 686 If the transaction failed, it can optionally return a specific failure
 687 status (normalized, not gateway-specific).  Currently defined statuses
 688 are: "expired", "nsf" (non-sufficient funds), "stolen", "pickup",
 689 "blacklisted" and "declined" (card/transaction declines only, not
 690 other errors).
 691
 692 Note that not all processor modules support this, and that if supported,
 693 it may not be set for all declines.
 694
 695 =head2 authorization()
 696
 697 If the transaction has been submitted and accepted, this function will
 698 provide you with the authorization code that the processor returned.
 699 Store this if you would like to run inquiries or refunds on the transaction
 700 later.
 701
 702 =head2 order_number()
 703
 704 The unique order number for the transaction generated by the gateway.  Store
 705 this if you would like to run inquiries or refunds on the transaction later.
 706
 707 =head2 card_token()
 708
 709 If supported by your gateway, a card_token can be used in a subsequent
 710 transaction to refer to a card number.
 711
 712 =head2 txn_date()
 713
 714 Transaction date, as returned by the gateway.  Required by some gateways
 715 for follow-up transactions.
 716
 717 =head2 fraud_score()
 718
 719 Retrieve or change the fraud score from any Business::FraudDetect plugin
 720
 721 =head2 fraud_transaction_id()
 722
 723 Retrieve or change the transaction id from any Business::FraudDetect plugin
 724
 725 =head2 response_code()
 726
 727 =head2 response_headers()
 728
 729 =head2 response_page()
 730
 731 These three fields are set by some processors (especially those which use
 732 HTTPS) when the transaction fails at the communication level rather than
 733 as a transaction.
 734
 735 response_code is the HTTP response code and message, i.e.
 736 '500 Internal Server Error'.
 737
 738 response_headers is a hash reference of the response headers
 739
 740 response_page is the raw content.
 741
 742 =head2 result_code()
 743
 744 Returns the precise result code that the processor returned, these are
 745 normally one letter codes that don't mean much unless you understand
 746 the protocol they speak, you probably don't need this, but it's there
 747 just in case.
 748
 749 =head2 avs_code()
 750
 751 =head2 cvv2_response()
 752
 753 =head1 MISCELLANEOUS INTERNAL METHODS
 754
 755 =head2 transaction_type()
 756
 757 Retrieve the transaction type (the 'type' argument to contents()).
 758 Generally only used internally, but provided in case it is useful.
 759
 760 =head2 server()
 761
 762 Retrieve or change the processor submission server address (CHANGE AT
 763 YOUR OWN RISK).
 764
 765 =head2 port()
 766
 767 Retrieve or change the processor submission port (CHANGE AT YOUR OWN
 768 RISK).
 769
 770 =head2 path()
 771
 772 Retrieve or change the processor submission path (CHANGE AT YOUR OWN
 773 RISK).
 774
 775 =head1 HELPER METHODS FOR GATEWAY MODULE AUTHORS
 776
 777 =head2 build_subs( @sub_names )
 778
 779 Build setter/getter subroutines for new return values.
 780
 781 =head2 get_fields( @fields )
 782
 783 Get the named fields if they are defined.
 784
 785 =head2 remap_fields( %map )
 786
 787 Remap field content (and stuff it back into content).
 788
 789 =head2 required_fields( @fields )
 790
 791 Croaks if any of the required fields are not present.
 792
 793 =head2 dump_contents
 794
 795 =head2 silly_bool( $value )
 796
 797 Returns 1 if the value starts with y, Y, t or T.
 798 Returns 0 if the value starts with n, N, f or F.
 799 Otherwise returns the value itself.
 800
 801 Use this for handling boolean content like tax_exempt.
 802
 803 =head1 AUTHORS
 804
 805 (v2 series)
 806
 807 Jason Kohles, email@jasonkohles.com
 808
 809 (v3 rewrite)
 810
 811 Ivan Kohler <ivan-business-onlinepayment@420.am>
 812
 813 Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
 814
 815 =head1 COPYRIGHT
 816
 817 Copyright (c) 1999-2004 Jason Kohles
 818 Copyright (c) 2004 Ivan Kohler
 819 Copyright (c) 2007-2015 Freeside Internet Services, Inc.
 820
 821 All rights reserved.
 822
 823 This program is free software; you can redistribute it and/or modify it under
 824 the same terms as Perl itself.
 825
 826 =head1 HOMEPAGE
 827
 828 Homepage:  http://perl.business/onlinepayment
 829
 830 Development:  http://perl.business/onlinepayment/ng.html
 831
 832 =head1 MAILING LIST
 833
 834 Please direct current development questions, patches, etc. to the mailing list:
 835 http://420.am/cgi-bin/mailman/listinfo/bop-devel/
 836
 837 =head1 REPOSITORY
 838
 839 The code is available from our public git repository:
 840
 841   git clone git://git.freeside.biz/Business-OnlinePayment.git
 842
 843 Or on the web:
 844
 845   http://freeside.biz/gitweb/?p=Business-OnlinePayment.git
 846   Or:
 847   http://freeside.biz/gitlist/Business-OnlinePayment.git
 848
 849 Many (but by no means all!) processor plugins are also available in the same
 850 repository, see:
 851
 852   http://freeside.biz/gitweb/
 853   Or:
 854   http://freeside.biz/gitlist/
 855
 856 =head1 DISCLAIMER
 857
 858 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
 859 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 860 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 861
 862 =head1 SEE ALSO
 863
 864 http://perl.business/onlinepayment
 865
 866 For verification of credit card checksums, see L<Business::CreditCard>.
 867
 868 =cut