Partial authorizations

diff --git a/Changes b/Changes
index 3ea8ab6..e5ee202 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1,6 +1,7 @@
 Revision history for Perl extension Business::OnlinePayment.
 
 3.04    unreleased
+        - Doc: Partial authorizations
         - Doc: Moo is a-okay for module authors
         - Doc: update URLs for new domain
 

diff --git a/OnlinePayment.pm b/OnlinePayment.pm
index c5ed1bd..6b32f40 100644 (file)
--- a/OnlinePayment.pm
+++ b/OnlinePayment.pm
@@ -6,7 +6,7 @@ use Carp;
 
 require 5.005;
 
-$VERSION = '3.04_01';
+$VERSION = '3.04_02';
 $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
@@ -416,6 +417,13 @@ Tax exempt flag (i.e. TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0).
 Currency, specified as an ISO 4217 three-letter code, such as USD, CAD, EUR,
 AUD, DKK, GBP, JPY, NZD, etc.
 
+=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.
+
 =back
 
 =head3 CUSTOMER INFO FIELDS
@@ -654,6 +662,15 @@ 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()
 
 If the transaction has been submitted but was not accepted, this

diff --git a/notes_for_module_writers_v3 b/notes_for_module_writers_v3
index 94b598f..7313e11 100644 (file)
--- a/notes_for_module_writers_v3
+++ b/notes_for_module_writers_v3
@@ -2,14 +2,17 @@ These are the module writer's notes for v3.  See the regular
 "notes_for_module_writers" file first.
 
 
-- If your gateway is HTTPS-based, use (or convert to)
+= Business::OnlinePayment::HTTPS =
+
+  If your gateway is HTTPS-based, use (or convert to)
   Business::OnlinePayment::HTTPS !!
+
   Note: The correct thing for modern B:OP: gateway modules that need to
    speak HTTPS to do is to use Business::OnlinePayment::HTTPS and depend on
    "Net::HTTPS::Any" (since B:OP itself doesn't).
 
 
-- Handling failures:
+= Handling failures =
 
     - If your processor module encounters a setup problem, communication
       error or other problem that's prevents the card from even being
@@ -32,7 +35,7 @@ These are the module writer's notes for v3.  See the regular
       - "decline" (other card/transaction declines only, not other errors)
   
 
-- (NEW IN 3.01) Introspection:
+= (NEW IN 3.01) Introspection =
 
   - Add an _info subroutine to your module that returns a hashref of
     information:
@@ -92,7 +95,7 @@ These are the module writer's notes for v3.  See the regular
       }
 
 
-- authorization and order_number (NEWLY DOCUMENTED IN 3.01):
+= authorization and order_number (NEWLY DOCUMENTED IN 3.01) =
 
   Gateways will return one or two values from Authorization Only and
   Normal Authorization transactions that must be submitted back with a
@@ -106,8 +109,34 @@ These are the module writer's notes for v3.  See the regular
   is a unique tranaction id generated by the gateway.
 
 
-- Moo (NEWLY DOCUMENTED IN 3.04)
+= Moo (NEWLY DOCUMENTED IN 3.04) =
 
   Feel free to write gateway modules which use Moo.  Please do not require
   Moo newer than 0.091011 at this time (until 2018 or so).
 
+
+= Partial authorizations (NEWLY DOCUMENTED IN 3.04) =
+
+  If your gateway supports partial authorizations:
+
+  - Declare this in your "sub _info" introspection subroutine:
+      'partial_auth' => 1,
+
+  - Add "partial_auth_amount to your build_subs call in set_defaults, or add
+    one:
+      $self->build_subs('partial_auth_amount');
+
+  - Honor the transaction 'partial_auth' flag as follows:
+    + If this transaction flag is unset, the application is not expecting to
+      handle a partial authorzation.  So, either set the gateway flag disabling
+      partial authorizations, or (if your gatweay does not have such a
+      setting), immediately void any partial authorization received and
+      return is_success 0.
+    + If this transaction flag is set, the application can handle a partial
+      authorization.  Make sure the flag to enable them is passed to the
+      gateway, if necessary.  When a partial authorization is received, the
+      amount must be returned as "partial_auth_amount":
+        $self->partial_auth_amount( $partial_amount );
+      For normal full authorizations, "partial_auth_amount" must not be set.
+
+