notes_for_module_writers

   1 Notes for module writers
   2 ------------------------
   3
   4 Usually talking to your gateway requires that you implement a class performing
   5 the Business::BatchPayment::Processor role. You may also need to implement a
   6 Business::BatchPayment::Transport.
   7
   8 The most common payment batch formats look something like:
   9
  10 HEADER ROW
  11 PAYMENT
  12 PAYMENT
  13 CREDIT (maybe)
  14 PAYMENT
  15 ...
  16 TRAILER ROW
  17
  18 where the rows are fixed-length records, possibly separated by newlines.
  19 The return file from the gateway follows a similar format in which each
  20 record identifies one of the transactions as approved or declined.
  21
  22 Business::BatchPayment is designed with this general structure in mind,
  23 but there are many variations and some gateways use completely different
  24 formats.
  25
  26 B:BP::Processor class
  27 ---------------------
  28
  29 The Processor class does the work of transforming the B:BP::Batch object
  30 and its associated Item objects into the format used by the gateway, and
  31 vice versa.
  32
  33 "Static" information like the merchant account number or the username and
  34 password for transmitting batches should be declared as attributes of the
  35 Processor class, using the "has" operator.
  36
  37 The external interface to the processor class is only two methods.
  38
  39 - submit( B:BP::Batch ): Prepares and submits a batch of payment requests.
  40
  41 - receive(): Returns any available batches of payment results from the
  42   gateway.
  43
  44 The base role provides default submit() and receive() methods that should
  45 work in most cases. The recommended interface is to provide the following
  46 methods:
  47
  48 format_header( B:BP::Batch ): Creates the start of the formatted batch
  49 (usually information such as your merchant account number and the date
  50 of submission, and sometimes a sum or count of the items). This defaults
  51 to an empty string.
  52
  53 format_item( B:BP::Item, B:BP::Batch ): Takes a single payment request item,
  54 and returns a string representing that item. This will be called for each
  55 item in the batch, in order. See Business::BatchPayment::Item for the
  56 attributes of the individual transactions.
  57
  58 format_trailer( B:BP::Batch ): Creates the trailer for the request document.
  59 This also defaults to an empty string.
  60
  61 parse_batch_id( CONTENT ): Given a result document, extracts the batch ID
  62 (as a string) and returns it.
  63
  64 parse_item( LINE ): Given a single line of the result document, returns a
  65 B:BP::Item (see perldoc there for details). This must contain "approved",
  66 and either "tid" or both "customer_id" and "amount".
  67
  68 default_transport: The default method for creating the B:BP::Transport object
  69 for sending the request document to the gateway and retrieving results. If
  70 the gateway uses HTTPS or SFTP in a straightforward way, you may be able
  71 to use one of the existing transport classes (passing the hostname and
  72 login credentials to the constructor). Otherwise, you may need to write
  73 a transport class. See below.
  74
  75 This is optional; if you don't provide a default transport, then the merchant
  76 system using B:BP just has to provide one of its own. This is the recommended
  77 way to deal with a batch upload that has to be done manually.
  78
  79 default_on_error: The exception handler for format_item or parse_item.
  80 Called with two arguments: the B:BP::Item object or data row, and the
  81 die() string. This is optional, and can be overridden by the on_format_error
  82 and on_parse_error attributes.
  83
  84
  85 If the gateway's batch format doesn't lend itself to a simple
  86 header/items/trailer division, you may need to override the higher-level
  87 methods:
  88
  89 format_request( B:BP::Batch ): Converts the entire batch to the format
  90 expected by the gateway. (By default this simply calls the above methods.)
  91
  92 parse_response( CONTENT ): Converts the entire reply document received from
  93 the gateway to a B:BP::Batch object. As above, each reply item must contain
  94 "approved", and either "tid" or both "customer_id" and "amount".
  95
  96 B:BP::Transport class
  97 ---------------------
  98
  99 This must implement two methods, "upload" and "download".
 100
 101 "upload" takes the batch content produced by format_request as an argument,
 102 and does whatever is necessary to send it to the gateway. "download" takes
 103 no arguments, and returns a list of strings containing batch results.
 104
 105 The "SFTP", "HTTPS", and "File" subclasses all have "upload" and "download"
 106 methods which may be suitable, but if not, they also expose access to their
 107 protocols. For example, if the file needs to be compressed before being
 108 submitted by SFTP, you could create a B:BP::Transport::SFTP subclass which
 109 provides an "upload" method. That method would compress the file and then
 110 call "$self->put" to send it to the host and path defined in the transport's
 111 attributes.
 112
 113 B:BP::TestMode
 114 --------------
 115
 116 Include this role in your Processor module if it supports a test mode.
 117 It will create a "test_mode" attribute which can be set to true; the processor
 118 or transport should check this attribute, and do whatever is necessary to
 119 enable test mode (submitting to a different server, setting a flag within
 120 the request itself, etc.).
 121
 122 If the processor doesn't have a test mode (or enables it on a per-account
 123 basis, i.e. test mode is selected by using a test login), then don't include
 124 this role, and attempts to set test_mode will simply fail.
 125
 126