3.05, add nacha_sec_code

[Business-OnlinePayment.git] / notes_for_module_writers_v3

diff --git a/notes_for_module_writers_v3 b/notes_for_module_writers_v3
index 94b598f..3376500 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:


@@ -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
           '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',
           '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 {
         {
 
       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,
           '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',
           'supported_actions'     => { 'CC' => [
                                          'Normal Authorization',
                                          'Authorization Only',
                                          'Post Authorization',
                                          'Void',
                                          'Credit',

+                                         'Tokenize',

                                          'Recurring Authorization',
                                          'Modify Recurring Authorization',
                                          'Cancel Recurring Authorization',
                                          '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_void_requires_card' => 1,

+          #? 'CC_reverse_auth_requires_txn_date' => 1,

           'ECHECK_void_requires_account' => 1, #routing_code, account_number, name 
         };
       }
 
 
           '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
 
   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"
 
 
   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.
 
 
   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).
 
 
   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.
+
+