X-Git-Url: http://git.freeside.biz/gitweb/?a=blobdiff_plain;f=notes_for_module_writers_v3;h=6b6480541606bb03f39c8697d3cfee80222f34d2;hb=72783a4ae656a3d75184d0210ab81c73e22867b6;hp=41ae2ddcd84ce65d02cc7fa737de3f75f7f0d3c6;hpb=e25139b75acbabb4b88e69c22d10976c949f769e;p=Business-OnlinePayment.git

diff --git a/notes_for_module_writers_v3 b/notes_for_module_writers_v3
index 41ae2dd..6b64805 100644
--- 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:
@@ -47,7 +50,7 @@ These are the module writer's notes for v3.  See the regular
           'supported_types'       => [ qw( CC ECHECK ) ],
           'token_support'         => 0, #card storage/tokenization support
           'test_transaction'      => 0, #set true if ->test_transaction(1) works
-          'partial_auth'          => 1, #can gateway partial auth (new in 3.04)
+          'partial_auth'          => 0, #can gateway partial auth (new in 3.04)
           'supported_actions'     => [
                                        'Normal Authorization',
                                        'Authorization Only',
@@ -58,7 +61,8 @@ These are the module writer's notes for v3.  See the regular
         };
       }
 
-    # or a more complicated case:
+    # or a more complicated case with module_notes, different supported actions
+    #  per type, and special void requirements:
 
       sub _info {
         {
@@ -71,6 +75,7 @@ These are the module writer's notes for v3.  See the regular
           'supported_types'       => [ qw( CC ECHECK ) ],
           'token_support'         => 1,
           'test_transaction'      => 1,
+          'partial_auth'          => 1, #can gateway partial auth (new in 3.04)
           'supported_actions'     => { 'CC' => [
                                          'Normal Authorization',
                                          'Authorization Only',
@@ -88,12 +93,13 @@ These are the module writer's notes for v3.  See the regular
                                        ],
                                      },
           'CC_void_requires_card' => 1,
+          #? 'CC_reverse_auth_requires_txn_date' => 1,
           'ECHECK_void_requires_account' => 1, #routing_code, account_number, name 
         };
       }
 
 
-- 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
@@ -107,18 +113,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 authorization (NEW in 3.04)
+
+= Partial authorizations (NEWLY DOCUMENTED IN 3.04) =
 
   If your gateway supports partial authorizations:
 
-  + Indicate this in the introspection _info subroutine (see above)
-  + Accept the partial_auth transaction field:
-    * if not explicitly set, partial authorizations should be reversed/voided
-      and returned as is_success 0
-    * if explicitly set, partial authorizations should return is_success 1
-      and the authorized amount as partial_auth_amount
+  - 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, return
+      is_success 1, and the amount as "partial_auth_amount":
+        $self->partial_auth_amount( $partial_amount );
+      For normal full authorizations, "partial_auth_amount" must not be set.
+
+