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
 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
 
         - 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;
 
 
 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()
 $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
     failure_status
     fraud_detect
     is_success

+    partial_auth_amount

     maximum_risk
     path
     port
     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.
 
 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
 =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.
 
 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
 =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.
 
 
 "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 !!
   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).
 
 
   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
 
     - 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)
   
 
       - "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:
 
   - 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
 
   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.
 
 
   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).
 
 
   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.
+
+