notes_for_module_writers_v3

   1 These are the module writer's notes for v3.  See the regular
   2 "notes_for_module_writers" file first.
   3
   4
   5 = Business::OnlinePayment::HTTPS =
   6
   7   If your gateway is HTTPS-based, use (or convert to)
   8   Business::OnlinePayment::HTTPS !!
   9
  10   Note: The correct thing for modern B:OP: gateway modules that need to
  11    speak HTTPS to do is to use Business::OnlinePayment::HTTPS and depend on
  12    "Net::HTTPS::Any" (since B:OP itself doesn't).
  13
  14
  15 = Handling failures =
  16
  17     - If your processor module encounters a setup problem, communication
  18       error or other problem that's prevents the card from even being
  19       run, you should die (or croak) with a useful error message.  Setting
  20       is_success to 0 and returning normally should only be done when the
  21       transaction *processing* was sucessful (or at least elicited some sort
  22       of result from the gateway), but the transaction itself returned a
  23       "normal" decline status of some sort.
  24
  25     - (NEW IN 3.00_04) You should set "failure_status" depending on the
  26       specific failure result, if (and only if) the failure results from one
  27       of the defined statuses:
  28
  29       - "expired"
  30       - "nsf" (non-sufficient funds / credit limit)
  31       - "stolen"
  32       - "pickup"
  33       - "blacklisted"
  34       - "inactive" (inactive card or not authorized for card-not-present) (?)
  35       - "decline" (other card/transaction declines only, not other errors)
  36
  37
  38 = (NEW IN 3.01) Introspection =
  39
  40   - Add an _info subroutine to your module that returns a hashref of
  41     information:
  42
  43       sub _info {
  44         {
  45           'info_compat'           => '0.01', # always 0.01 for now,
  46                                              # 0.02 will have requirements
  47           'gateway_name'          => 'Example Gateway',
  48           'gateway_url'           => 'http://www.example.com/',
  49           'module_version'        => $VERSION,
  50           'supported_types'       => [ qw( CC ECHECK ) ],
  51           'token_support'         => 0, #card storage/tokenization support
  52           'test_transaction'      => 0, #set true if ->test_transaction(1) works
  53           'partial_auth'          => 0, #can gateway partial auth (new in 3.04)
  54           'supported_actions'     => [
  55                                        'Normal Authorization',
  56                                        'Authorization Only',
  57                                        'Post Authorization',
  58                                        'Void',
  59                                        'Credit',
  60                                      ],
  61         };
  62       }
  63
  64     # or a more complicated case with module_notes, different supported actions
  65     #  per type, and special void requirements:
  66
  67       sub _info {
  68         {
  69           'info_compat'           => '0.01', # always 0.01 for now,
  70                                              # 0.02 will have requirements
  71           'gateway_name'          => 'Example Gateway',
  72           'gateway_url'           => 'http://www.example.com/',
  73           'module_version'        => $VERSION,
  74           'module_notes'          => 'usage notes',
  75           'supported_types'       => [ qw( CC ECHECK ) ],
  76           'token_support'         => 1,
  77           'test_transaction'      => 1,
  78           'partial_auth'          => 1, #can gateway partial auth (new in 3.04)
  79           'supported_actions'     => { 'CC' => [
  80                                          'Normal Authorization',
  81                                          'Authorization Only',
  82                                          'Post Authorization',
  83                                          'Void',
  84                                          'Credit',
  85                                          'Recurring Authorization',
  86                                          'Modify Recurring Authorization',
  87                                          'Cancel Recurring Authorization',
  88                                        ],
  89                                        'ECHECK' => [
  90                                          'Normal Authorization',
  91                                          'Void',
  92                                          'Credit',
  93                                        ],
  94                                      },
  95           'CC_void_requires_card' => 1,
  96           #? 'CC_reverse_auth_requires_txn_date' => 1,
  97           'ECHECK_void_requires_account' => 1, #routing_code, account_number, name
  98         };
  99       }
 100
 101
 102 = authorization and order_number (NEWLY DOCUMENTED IN 3.01) =
 103
 104   Gateways will return one or two values from Authorization Only and
 105   Normal Authorization transactions that must be submitted back with a
 106   Post Authorization, Void, or Credit transaction.
 107
 108   If the gateway returns one value, return this as "authorization"
 109
 110   If the gateway returns two values, return one as "authorization" and the
 111   other as "order_number".  Typically "authorization" is the more low-level
 112   value returned from the underlying processing network while "order_number"
 113   is a unique tranaction id generated by the gateway.
 114
 115
 116 = Moo (NEWLY DOCUMENTED IN 3.04) =
 117
 118   Feel free to write gateway modules which use Moo.  Please do not require
 119   Moo newer than 0.091011 at this time (until 2018 or so).
 120
 121
 122 = Partial authorizations (NEWLY DOCUMENTED IN 3.04) =
 123
 124   If your gateway supports partial authorizations:
 125
 126   - Declare this in your "sub _info" introspection subroutine:
 127       'partial_auth' => 1,
 128
 129   - Add "partial_auth_amount" to your build_subs call in set_defaults, or add
 130     one:
 131       $self->build_subs('partial_auth_amount');
 132
 133   - Honor the transaction 'partial_auth' flag as follows:
 134     + If this transaction flag is unset, the application is not expecting to
 135       handle a partial authorzation.  So, either set the gateway flag disabling
 136       partial authorizations, or (if your gatweay does not have such a
 137       setting), immediately void any partial authorization received and
 138       return is_success 0.
 139     + If this transaction flag is set, the application can handle a partial
 140       authorization.  Make sure the flag to enable them is passed to the
 141       gateway, if necessary.  When a partial authorization is received, return
 142       is_success 1, and the amount as "partial_auth_amount":
 143         $self->partial_auth_amount( $partial_amount );
 144       For normal full authorizations, "partial_auth_amount" must not be set.
 145
 146