3.00

[Business-OnlinePayment.git] / OnlinePayment.pm

diff --git a/OnlinePayment.pm b/OnlinePayment.pm
index c8f7438..a3a262f 100644 (file)
--- a/OnlinePayment.pm
+++ b/OnlinePayment.pm
@@ -6,45 +6,45 @@ use Carp;
 
 require 5.005;
 
 
 require 5.005;
 

-$VERSION = '3.00_04';
+$VERSION = '3.00';

 $VERSION = eval $VERSION; # modperlstyle: convert the string into a number
 
 # Remember subclasses we have "wrapped" submit() with _pre_submit()
 my %Presubmit_Added = ();
 
 my %fields = (
 $VERSION = eval $VERSION; # modperlstyle: convert the string into a number
 
 # Remember subclasses we have "wrapped" submit() with _pre_submit()
 my %Presubmit_Added = ();
 
 my %fields = (

-    authorization    => undef,
-    error_message    => undef,
-    failure_status   => undef,
-    fraud_detect     => undef,
-    is_success       => undef,
-    maximum_risk     => undef,
-    path             => undef,
-    port             => undef,
-    require_avs      => undef,
-    result_code      => undef,
-    server           => undef,
-    server_response  => undef,
-    test_transaction => undef,
-    transaction_type => undef,
+    authorization        => undef,
+    error_message        => undef,
+    failure_status       => undef,
+    fraud_detect         => undef,
+    is_success           => undef,
+    maximum_risk         => undef,
+    path                 => undef,
+    port                 => undef,
+    require_avs          => undef,
+    result_code          => undef,
+    server               => undef,
+    server_response      => undef,
+    test_transaction     => undef,
+    transaction_type     => undef,
+    fraud_score          => undef,
+    fraud_transaction_id => undef,

 );
 
 sub new {
     my($class,$processor,%data) = @_;
 
 );
 
 sub new {
     my($class,$processor,%data) = @_;
 

-    Carp::croak("unspecified processor") unless $processor;
+    croak("unspecified processor") unless $processor;

 
     my $subclass = "${class}::$processor";
 
     my $subclass = "${class}::$processor";

-    if(!defined(&$subclass)) {
-        eval "use $subclass";
-        Carp::croak("unknown processor $processor ($@)") if $@;
-    }
+    eval "use $subclass";
+    croak("unknown processor $processor ($@)") if $@;

 
     my $self = bless {processor => $processor}, $subclass;
     $self->build_subs(keys %fields);
 
     if($self->can("set_defaults")) {
 
     my $self = bless {processor => $processor}, $subclass;
     $self->build_subs(keys %fields);
 
     if($self->can("set_defaults")) {

-        $self->set_defaults();
+        $self->set_defaults(%data);

     }
 
     foreach(keys %data) {
     }
 
     foreach(keys %data) {


@@ -80,6 +80,8 @@ sub _risk_detect {
     $risk_transaction->content( %parent_content );
     $risk_transaction->submit();
     if ($risk_transaction->is_success()) {
     $risk_transaction->content( %parent_content );
     $risk_transaction->submit();
     if ($risk_transaction->is_success()) {

+         $self->fraud_score( $risk_transaction->fraud_score );
+         $self->fraud_transaction_id( $risk_transaction->fraud_transaction_id );

        if ( $risk_transaction->fraud_score <= $self->maximum_fraud_score()) {
            return 1;
        } else {
        if ( $risk_transaction->fraud_score <= $self->maximum_fraud_score()) {
            return 1;
        } else {


@@ -92,6 +94,8 @@ sub _risk_detect {
     return 0;
 }
 
     return 0;
 }
 

+my @Fraud_Class_Path = qw(Business::OnlinePayment Business::FraudDetect);
+

 sub _pre_submit {
     my ($self) = @_;
     my $fraud_detection = $self->fraud_detect();
 sub _pre_submit {
     my ($self) = @_;
     my $fraud_detection = $self->fraud_detect();


@@ -100,26 +104,25 @@ sub _pre_submit {
     return 1 unless $fraud_detection;
 
     # Search for an appropriate FD module
     return 1 unless $fraud_detection;
 
     # Search for an appropriate FD module

-    foreach my $subclass ( q(Business::OnlinePayment::) . $fraud_detection,
-                          q(Business::FraudDetect::) . $fraud_detection) {
-
-       if (!defined(&$subclass)) {
-           eval "use $subclass";
-           if ($@) {
-               Carp::croak("serious problem loading fraud_detection module ($@)") unless
-                   $@ =~ m/^Can\'t locate/;
-           } else {
-               my $risk_tx = bless ( { processor => $fraud_detection } , $subclass );
-               $risk_tx->build_subs(keys %fields);
-               if ($risk_tx->can('set_defaults')) {
-                   $risk_tx->set_defaults();
-               }
-               $risk_tx->_glean_parameters_from_parent($self);
-               return $self->_risk_detect($risk_tx);
-           }
+    foreach my $fraud_class ( @Fraud_Class_Path ) {
+       my $subclass = $fraud_class . "::" . $fraud_detection;
+       eval "use $subclass ()";
+       if ($@) {
+           croak("error loading fraud_detection module ($@)")
+              unless ( $@ =~ m/^Can\'t locate/ );
+        } else {
+            my $risk_tx = bless( { processor => $fraud_detection }, $subclass );
+            $risk_tx->build_subs(keys %fields);
+            if ($risk_tx->can('set_defaults')) {
+                $risk_tx->set_defaults();
+            }
+            $risk_tx->_glean_parameters_from_parent($self);
+            return $self->_risk_detect($risk_tx);

        }
     }
        }
     }

-    return 1; # BUG?: success if fraud_detection module not found!
+    croak("Unable to locate fraud_detection module $fraud_detection"
+               . " in \@INC under Fraud_Class_Path (\@Fraud_Class_Path"
+               . " contains: @Fraud_Class_Path) (\@INC contains: @INC)");

 }
 
 sub content {
 }
 
 sub content {


@@ -141,7 +144,7 @@ sub required_fields {
         push(@missing, $_) unless exists $content{$_};
     }
 
         push(@missing, $_) unless exists $content{$_};
     }
 

-    Carp::croak("missing required field(s): " . join(", ", @missing) . "\n")
+    croak("missing required field(s): " . join(", ", @missing) . "\n")

          if(@missing);
 }
 
          if(@missing);
 }
 


@@ -169,7 +172,7 @@ sub remap_fields {
 sub submit {
     my($self) = @_;
 
 sub submit {
     my($self) = @_;
 

-    Carp::croak("Processor subclass did not override submit function");
+    croak("Processor subclass did not override submit function");

 }
 
 sub dump_contents {
 }
 
 sub dump_contents {


@@ -247,13 +250,9 @@ little depending on the processor, so we have chosen to use a system
 which defines specific fields in the frontend which get mapped to the
 correct fields in the backend.  The currently defined fields are:
 
 which defines specific fields in the frontend which get mapped to the
 correct fields in the backend.  The currently defined fields are:
 

-=over 4
+=head3 PROCESSOR FIELDS

 
 

-=item * type
-
-Transaction type, supported types are:
-Visa, MasterCard, American Express, Discover, Check (not all
-processors support all these transaction types).
+=over 4

 
 =item * login
 
 
 =item * login
 


@@ -263,10 +262,25 @@ Your login name to use for authentication to the online processor.
 
 Your password to use for authentication to the online processor.
 
 
 Your password to use for authentication to the online processor.
 

+=back
+
+=head3 GENERAL TRANSACTION FIELDS
+
+=over 4
+
+=item * type
+
+Transaction type, supported types are: CC (credit card), ECHECK
+(electronic check) and LEC (phone bill billing).  Deprecated types
+are: Visa, MasterCard, American Express, Discover, Check (not all
+processors support all these transaction types).
+

 =item * action
 
 What to do with the transaction (currently available are: Normal
 =item * action
 
 What to do with the transaction (currently available are: Normal

-Authorization, Authorization Only, Credit, Post Authorization)
+Authorization, Authorization Only, Credit, Post Authorization,
+Recurring Authorization, Modify Recurring Authorization,
+Cancel Recurring Authorization)

 
 =item * description
 
 
 =item * description
 


@@ -283,38 +297,74 @@ and the like, just a floating point number.
 An invoice number, for your use and not normally required, many
 processors require this field to be a numeric only field.
 
 An invoice number, for your use and not normally required, many
 processors require this field to be a numeric only field.
 

+=back
+
+=head3 CUSTOMER INFO FIELDS
+
+=over 4
+

 =item * customer_id
 
 A customer identifier, again not normally required.
 
 =item * name
 
 =item * customer_id
 
 A customer identifier, again not normally required.
 
 =item * name
 

-The customers name, your processor may not require this.
+The customer's name, your processor may not require this.
+
+=item * first_name
+
+=item * last_name
+
+The customer's first and last name as separate fields.
+
+=item * company
+
+The customer's company name, not normally required.

 
 =item * address
 
 
 =item * address
 

-The customers address (your processor may not require this unless you
+The customer's address (your processor may not require this unless you

 are requiring AVS Verification).
 
 =item * city
 
 are requiring AVS Verification).
 
 =item * city
 

-The customers city (your processor may not require this unless you are
-requiring AVS Verification).
+The customer's city (your processor may not require this unless you
+are requiring AVS Verification).

 
 =item * state
 
 
 =item * state
 

-The customers state (your processor may not require this unless you
+The customer's state (your processor may not require this unless you

 are requiring AVS Verification).
 
 =item * zip
 
 are requiring AVS Verification).
 
 =item * zip
 

-The customers zip code (your processor may not require this unless you
-are requiring AVS Verification).
+The customer's zip code (your processor may not require this unless
+you are requiring AVS Verification).

 
 =item * country
 
 Customer's country.
 
 
 =item * country
 
 Customer's country.
 

+=item * ship_first_name
+
+=item * ship_last_name
+
+=item * ship_company
+
+=item * ship_address
+
+=item * ship_city
+
+=item * ship_state
+
+=item * ship_zip
+
+=item * ship_country
+
+These shipping address fields may be accepted by your processor.
+Refer to the description for the corresponding non-ship field for
+general information on each field.
+

 =item * phone
 
 Customer's phone number.
 =item * phone
 
 Customer's phone number.


@@ -327,28 +377,117 @@ Customer's fax number.
 
 Customer's email address.
 
 
 Customer's email address.
 

+=item * customer_ip
+
+IP Address from which the transaction originated.
+
+=back
+
+=head3 CREDIT CARD FIELDS
+
+=over 4
+

 =item * card_number
 
 =item * card_number
 

-Credit card number (obviously not required for non-credit card
-transactions).
+Credit card number.
+
+=item * cvv2
+
+CVV2 number (also called CVC2 or CID) is a three- or four-digit
+security code used to reduce credit card fraud.

 
 =item * expiration
 
 
 =item * expiration
 

-Credit card expiration (obviously not required for non-credit card
-transactions).
+Credit card expiration.
+
+=item * track1
+
+Track 1 on the magnetic stripe (Card present only)
+
+=item * track2
+
+Track 2 on the magnetic stripe (Card present only)
+
+=item * recurring billing
+
+Recurring billing flag
+
+=back
+
+=head3 ELECTRONIC CHECK FIELDS
+
+=over 4

 
 =item * account_number
 
 
 =item * account_number
 

-Bank account number for electronic checks or electronic funds transfer.
+Bank account number for electronic checks or electronic funds
+transfer.

 
 =item * routing_code
 
 
 =item * routing_code
 

-Bank's routing code for electronic checks or electronic funds transfer.
+Bank's routing code for electronic checks or electronic funds
+transfer.
+
+=item * account_type
+
+Account type for electronic checks or electronic funds transfer.  Can be
+(case-insensitive): B<Personal Checking>, B<Personal Savings>,
+B<Business Checking> or B<Business Savings>.
+
+=item * account_name
+
+Account holder's name for electronic checks or electronic funds
+transfer.

 
 =item * bank_name
 
 Bank's name for electronic checks or electronic funds transfer.
 
 
 =item * bank_name
 
 Bank's name for electronic checks or electronic funds transfer.
 

+=item * check_type
+
+Check type for electronic checks or electronic funds transfer.
+
+=item * customer_org
+
+Customer organization type.
+
+=item * customer_ssn
+
+Customer's social security number.  Typically only required for
+electronic checks or electronic funds transfer.
+
+=item * license_num
+
+Customer's driver's license number.  Typically only required for
+electronic checks or electronic funds transfer.
+
+=item * license_dob
+
+Customer's date of birth.  Typically only required for electronic
+checks or electronic funds transfer.
+
+=back
+
+=head3 RECURRING BILLING FIELDS
+
+=over 4
+
+=item * interval 
+
+Interval expresses the amount of time between billings: digits, whitespace
+and units (currently "days" or "months" in either singular or plural form).
+
+=item * start
+
+The date of the first transaction (used for processors which allow delayed
+start) expressed as YYYY-MM-DD.
+
+=item * periods
+
+The number of cycles of interval length for which billing should occur 
+(inclusive of 'trial periods' if the processor supports recurring billing
+at more than one rate)
+

 =back
 
 =head2 submit();
 =back
 
 =head2 submit();


@@ -362,11 +501,11 @@ it failed (or undef if it has not been submitted yet).
 
 =head2 failure_status();
 
 
 =head2 failure_status();
 

-If the transaction failed, it can optionally return a specific
-failure status (normalized, not gateway-specific).  Currently defined
-statuses are: "expired", "nsf" (non-sufficient funds), "stolen",
-"pickup", "blacklisted" and "declined" (card/transaction declines
-only, not other errors).
+If the transaction failed, it can optionally return a specific failure
+status (normalized, not gateway-specific).  Currently defined statuses
+are: "expired", "nsf" (non-sufficient funds), "stolen", "pickup",
+"blacklisted" and "declined" (card/transaction declines only, not
+other errors).

 
 Note that (as of Aug 2006) this is only supported by some of the
 newest processor modules, and that, even if supported, a failure
 
 Note that (as of Aug 2006) this is only supported by some of the
 newest processor modules, and that, even if supported, a failure


@@ -395,7 +534,7 @@ verification (if the processor supports it).
 
 =head2 transaction_type();
 
 
 =head2 transaction_type();
 

-Retrieve the transaction type (the 'type' argument to contents();).
+Retrieve the transaction type (the 'type' argument to contents()).

 Generally only used internally, but provided in case it is useful.
 
 =head2 error_message();
 Generally only used internally, but provided in case it is useful.
 
 =head2 error_message();


@@ -416,11 +555,21 @@ YOUR OWN RISK).
 
 =head2 port();
 
 
 =head2 port();
 

-Retrieve or change the processor submission port (CHANGE AT YOUR OWN RISK).
+Retrieve or change the processor submission port (CHANGE AT YOUR OWN
+RISK).

 
 =head2 path();
 
 
 =head2 path();
 

-Retrieve or change the processor submission path (CHANGE AT YOUR OWN RISK).
+Retrieve or change the processor submission path (CHANGE AT YOUR OWN
+RISK).
+
+=head2 fraud_score();
+
+Retrieve or change the fraud score from any Business::FraudDetect plugin
+
+=head2 fraud_transaction_id();
+
+Retrieve or change the transaction id from any Business::FraudDetect plugin

 
 =head1 AUTHORS
 
 
 =head1 AUTHORS
 


@@ -430,6 +579,35 @@ Jason Kohles, email@jasonkohles.com
 
 Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
 
 
 Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
 

+=head1 HOMEPAGE
+
+Homepage:  http://420.am/business-onlinepayment/
+
+Development:  http://420.am/business-onlinepayment/ng.html
+
+=head1 MAILING LIST
+
+Please direct current development questions, patches, etc. to the mailing list:
+http://420.am/cgi-bin/mailman/listinfo/bop-devel/
+
+=head1 REPOSITORY
+
+The code is available from our public CVS repository:
+
+  export CVSROOT=":pserver:anonymous@cvs.freeside.biz:/home/cvs/cvsroot"
+  cvs login
+  # The password for the user `anonymous' is `anonymous'.
+  cvs checkout Business-OnlinePayment
+
+Or on the web:
+
+  http://freeside.biz/cgi-bin/viewvc.cgi/Business-OnlinePayment/
+
+Many (but by no means all!) processor plugins are also available in the same
+repository, see:
+
+  http://freeside.biz/cgi-bin/viewvc.cgi/
+

 =head1 DISCLAIMER
 
 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
 =head1 DISCLAIMER
 
 THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED