X-Git-Url: http://git.freeside.biz/gitweb/?a=blobdiff_plain;ds=sidebyside;f=notes_for_module_writers_v3;h=3376500b5924d441e77656e30575c2cd9fb5b7a4;hb=90b8472dd1f760092933acf0b1a366de2caf9caf;hp=94b598f75013a52934dc34f1dc3124e9fe475f26;hpb=990795fc414232fb5ab67aa5dbc837e5b656b140;p=Business-OnlinePayment.git

diff --git a/notes_for_module_writers_v3 b/notes_for_module_writers_v3
index 94b598f..3376500 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,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',
@@ -57,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 {
         {
@@ -70,12 +75,14 @@ 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',
                                          'Post Authorization',
                                          'Void',
                                          'Credit',
+                                         'Tokenize',
                                          'Recurring Authorization',
                                          'Modify Recurring Authorization',
                                          'Cancel Recurring Authorization',
@@ -87,16 +94,17 @@ 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
-  Post Authorization, Void, or Credit transaction.
+  Post Authorization, Reverse Authorization, Void, or Credit transaction.
 
   If the gateway returns one value, return this as "authorization"
 
@@ -106,8 +114,49 @@ 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)
+= txn_date (NEW IN 3.05) =
+
+  Some gateways return a transaction date from Authorization Only / Normal
+  Authorization transactions that must be submitted back for a follow-up
+  Post Authorization, Reverse Authorization, Void, or Credit transaction.
+
+  For the most compatibility with all gateways for follow-up transactions,
+  pass this as well as authorization and order number.  Note this field is
+  a recent addition, so always access it like this:
+
+    my $txn_date =   $bop_transaction_object->can('txn_date')
+                   ? $bop_transaction_object->txn_date
+                   : '';
+
+
+= 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 gateway 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.
+
+