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

diff --git a/notes_for_module_writers_v3 b/notes_for_module_writers_v3
index 7dc4425..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
@@ -31,16 +34,8 @@ These are the module writer's notes for v3.  See the regular
       - "inactive" (inactive card or not authorized for card-not-present) (?)
       - "decline" (other card/transaction declines only, not other errors)
   
-      You should use code like this so your module can work with B:OP versions
-      before 3.00_04:
-
-        $self->build_subs('failure_status') unless $self->can('failure_status');
-
-      (or add "failure_status" to your build_subs call if you have one during
-      initialization)
 
-
-- (NEW IN 3.01) Introspection:
+= (NEW IN 3.01) Introspection =
 
   - Add an _info subroutine to your module that returns a hashref of
     information:
@@ -55,6 +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'          => 0, #can gateway partial auth (new in 3.04)
           'supported_actions'     => [
                                        'Normal Authorization',
                                        'Authorization Only',
@@ -65,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 {
         {
@@ -78,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',
@@ -95,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
@@ -114,8 +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 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, 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.
+
 
-  Feel free to write gateway modules which use Moo.  It would be appreciated
-  if you did not use features which required Moo newer than 0.091011 at this
-  time (2014 - 2018).