Add txn_date to return fields (and build_subs)

[Business-OnlinePayment.git] / OnlinePayment.pm

diff --git a/OnlinePayment.pm b/OnlinePayment.pm
index 0c9d2ff..b4404fe 100644 (file)
--- a/OnlinePayment.pm
+++ b/OnlinePayment.pm
@@ -6,7 +6,7 @@ use Carp;
 
 require 5.005;
 
-$VERSION = '3.02_02';
+$VERSION = '3.05_01';
 $VERSION = eval $VERSION; # modperlstyle: convert the string into a number
 
 # Remember subclasses we have "wrapped" submit() with _pre_submit()
@@ -19,6 +19,7 @@ my @methods = qw(
     failure_status
     fraud_detect
     is_success
+    partial_auth_amount
     maximum_risk
     path
     port
@@ -33,8 +34,13 @@ my @methods = qw(
     response_code
     response_header
     response_page
+    avs_code
+    cvv2_response
+    txn_date
 );
 
+__PACKAGE__->build_subs(@methods);
+
 #fallback
 sub _info {
   my $class = shift;
@@ -86,7 +92,6 @@ sub new {
     croak("unknown processor $processor ($@)") if $@;
 
     my $self = bless {processor => $processor}, $subclass;
-    $self->build_subs(@methods);
 
     if($self->can("set_defaults")) {
         $self->set_defaults(%data);
@@ -157,7 +162,6 @@ sub _pre_submit {
               unless ( $@ =~ m/^Can\'t locate/ );
         } else {
             my $risk_tx = bless( { processor => $fraud_detection }, $subclass );
-            $risk_tx->build_subs(@methods);
             if ($risk_tx->can('set_defaults')) {
                 $risk_tx->set_defaults();
             }
@@ -270,15 +274,24 @@ Business::OnlinePayment - Perl extension for online payment processing
                         type        => 'Visa',
                         amount      => '49.95',
                         card_number => '1234123412341238',
-                        expiration  => '0100',
+                        expiration  => '06/15',
                         name        => 'John Q Doe',
                        );
-  $transaction->submit();
-  
-  if($transaction->is_success()) {
-    print "Card processed successfully: ", $transaction->authorization(), "\n";
+
+  eval { $transaction->submit(); };
+
+  if ( $@ ) {
+
+    print "$processor error: $@\n";
+
   } else {
-    print "Card was rejected: ", $transaction->error_message(), "\n";
+  
+    if ( $transaction->is_success() ) {
+      print "Card processed successfully: ". $transaction->authorization()."\n";
+    } else {
+      print "Card was rejected: ". $transaction->error_message(). "\n";
+    }
+
   }
 
 =head1 DESCRIPTION
@@ -345,6 +358,8 @@ What action being taken by this transaction. Currently available are:
 
 =item Post Authorization
 
+=item Reverse Authorization
+
 =item Void
 
 =item Credit
@@ -368,6 +383,16 @@ just a whole or floating point number (i.e. 26, 26.1 or 26.13).
 
 =over 4
 
+=item partial_auth
+
+If you are prepared to handle partial authorizations
+(see L<partial_auth_amount()|/"partial_auth_amount()">
+ in L<TRANSACTION RESULT FIELDS|/"TRANSACTION RESULT FIELDS">),
+pass a true value in this field to enable them.
+
+If this flag is not set, a partial authorization will be immediately reversed
+or voided.
+
 =item description
 
 A description of the transaction (used by some processors to send
@@ -499,7 +524,7 @@ Credit card number.
 
 =item expiration
 
-Credit card expiration.
+Credit card expiration, MM/YY.
 
 =item cvv2
 
@@ -627,14 +652,28 @@ verification (if the processor supports it).
 
 =head2 submit()
 
-Submit the transaction to the processor for completion
+Submit the transaction to the processor for completion.
+
+If there is a gateway communication error or other "meta" , the submit method
+will throw a fatal exception.  You can catch this with eval {} if you would
+like to treat gateway co
 
 =head1 TRANSACTION RESULT METHODS
 
 =head2 is_success()
 
-Returns true if the transaction was submitted successfully, false if
-it failed (or undef if it has not been submitted yet).
+Returns true if the transaction was approved by the gateway, false if 
+it was submitted but not approved, or undef if it has not been 
+submitted yet.
+
+=head2 partial_auth_amount()
+
+If this transaction was a partial authorization (i.e. successful, but less than
+the requested amount was processed), then the amount processed is returned in
+this field.
+
+(When is_success is true but this field is empty or 0, that indicates a normal
+full authorization for the entire requested amount.)
 
 =head2 error_message()
 
@@ -650,10 +689,8 @@ 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
-status is an entirely optional field that is only set for specific
-kinds of failures.
+Note that not all processor modules support this, and that if supported,
+it may not be set for all declines.
 
 =head2 authorization()
 
@@ -672,6 +709,11 @@ this if you would like to run inquiries or refunds on the transaction later.
 If supported by your gateway, a card_token can be used in a subsequent
 transaction to refer to a card number.
 
+=head2 txn_date()
+
+Transaction date, as returned by the gateway.  Required by some gateways
+for follow-up transactions.
+
 =head2 fraud_score()
 
 Retrieve or change the fraud score from any Business::FraudDetect plugin
@@ -752,8 +794,8 @@ Croaks if any of the required fields are not present.
 
 =head2 silly_bool( $value )
 
-Returns 0 if the value starts with y, Y, t or T.
-Returns 1 if the value starts with n, N, f or F.
+Returns 1 if the value starts with y, Y, t or T.
+Returns 0 if the value starts with n, N, f or F.
 Otherwise returns the value itself.
 
 Use this for handling boolean content like tax_exempt.
@@ -774,7 +816,7 @@ Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
 
 Copyright (c) 1999-2004 Jason Kohles
 Copyright (c) 2004 Ivan Kohler
-Copyright (c) 2007-2011 Freeside Internet Services, Inc.
+Copyright (c) 2007-2015 Freeside Internet Services, Inc.
 
 All rights reserved.
 
@@ -783,9 +825,9 @@ the same terms as Perl itself.
 
 =head1 HOMEPAGE
 
-Homepage:  http://420.am/business-onlinepayment/
+Homepage:  http://perl.business/onlinepayment
 
-Development:  http://420.am/business-onlinepayment/ng.html
+Development:  http://perl.business/onlinepayment/ng.html
 
 =head1 MAILING LIST
 
@@ -794,21 +836,22 @@ http://420.am/cgi-bin/mailman/listinfo/bop-devel/
 
 =head1 REPOSITORY
 
-The code is available from our public CVS repository:
+The code is available from our public git 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
+  git clone git://git.freeside.biz/Business-OnlinePayment.git
 
 Or on the web:
 
-  http://freeside.biz/cgi-bin/viewvc.cgi/Business-OnlinePayment/
+  http://freeside.biz/gitweb/?p=Business-OnlinePayment.git
+  Or:
+  http://freeside.biz/gitlist/Business-OnlinePayment.git
 
 Many (but by no means all!) processor plugins are also available in the same
 repository, see:
 
-  http://freeside.biz/cgi-bin/viewvc.cgi/
+  http://freeside.biz/gitweb/
+  Or:
+  http://freeside.biz/gitlist/
 
 =head1 DISCLAIMER
 
@@ -818,7 +861,7 @@ MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 
 =head1 SEE ALSO
 
-http://420.am/business-onlinepayment/
+http://perl.business/onlinepayment
 
 For verification of credit card checksums, see L<Business::CreditCard>.