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