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
   8     - Business::OnlinePayment::OpenECHO is the first "v3-ish" module, try
   9       starting from there.
  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       You should use code like this so your module can work with B:OP versions
  35       before 3.00_04:
  36
  37         $self->build_subs('failure_status') unless $self->can('failure_status');
  38
  39       (or add "failure_status" to your build_subs call if you have one during
  40       initialization)
  41
  42
  43 - (NEW IN 3.01) Introspection:
  44
  45   - Add an _info subroutine to your module that returns a hashref of
  46     information:
  47
  48       sub _info {
  49         {
  50           'info_compat'           => '0.01', # always 0.01 for now,
  51                                              # 0.02 will have requirements
  52           'gateway_name'          => 'Example Gateway',
  53           'gateway_url'           => 'http://www.example.com/',
  54           'module_version'        => $VERSION,
  55           'supported_types'       => [ qw( CC ECHECK ) ],
  56           'supported_actions'     => [
  57                                        'Normal Authorization',
  58                                        'Authorization Only',
  59                                        'Post Authorization',
  60                                        'Void',
  61                                        'Credit',
  62                                      ],
  63         };
  64       }
  65
  66     # or a more complicated case:
  67
  68       sub _info {
  69         {
  70           'info_compat'           => '0.01', # always 0.01 for now,
  71                                              # 0.02 will have requirements
  72           'gateway_name'          => 'Example Gateway',
  73           'gateway_url'           => 'http://www.example.com/',
  74           'module_version'        => $VERSION,
  75           'module_notes'          => 'usage notes',
  76           'supported_types'       => [ qw( CC ECHECK ) ],
  77           'supported_actions'     => { 'CC' => [
  78                                          'Normal Authorization',
  79                                          'Authorization Only',
  80                                          'Post Authorization',
  81                                          'Void',
  82                                          'Credit',
  83                                          'Recurring Authorization',
  84                                          'Modify Recurring Authorization',
  85                                          'Cancel Recurring Authorization',
  86                                        ],
  87                                        'ECHECK' => [
  88                                          'Normal Authorization',
  89                                          'Void',
  90                                          'Credit',
  91                                        ],
  92                                      },
  93           'CC_void_requires_card' => 1,
  94         };
  95       }
  96
  97
  98 - authorization and order_number (NEWLY DOCUMENTED IN 3.01):
  99
 100   Gateways will return one or two values from Authorization Only and
 101   Normal Authorization transactions that must be submitted back with a
 102   Post Authorization, Void, or Credit transaction.
 103
 104   If the gateway returns one value, return this as "authorization"
 105
 106   If the gateway returns two values, return one as "authorization" and the
 107   other as "order_number".  Typically "authorization" is the more low-level
 108   value returned from the underlying processing network while "order_number"
 109   is a unique tranaction id generated by the gateway.
 110