From: Mark Wells Date: Wed, 18 Feb 2015 05:27:13 +0000 (-0800) Subject: add notes_for_module_writers X-Git-Url: http://git.freeside.biz/gitweb/?p=Business-BatchPayment.git;a=commitdiff_plain;h=ca648e1ba593d759c74c062bf4056f7932982079 add notes_for_module_writers --- diff --git a/notes_for_module_writers b/notes_for_module_writers new file mode 100644 index 0000000..cd99cc5 --- /dev/null +++ b/notes_for_module_writers @@ -0,0 +1,126 @@ +Notes for module writers +------------------------ + +Usually talking to your gateway requires that you implement a class performing +the Business::BatchPayment::Processor role. You may also need to implement a +Business::BatchPayment::Transport. + +The most common payment batch formats look something like: + +HEADER ROW +PAYMENT +PAYMENT +CREDIT (maybe) +PAYMENT +... +TRAILER ROW + +where the rows are fixed-length records, possibly separated by newlines. +The return file from the gateway follows a similar format in which each +record identifies one of the transactions as approved or declined. + +Business::BatchPayment is designed with this general structure in mind, +but there are many variations and some gateways use completely different +formats. + +B:BP::Processor class +--------------------- + +The Processor class does the work of transforming the B:BP::Batch object +and its associated Item objects into the format used by the gateway, and +vice versa. + +"Static" information like the merchant account number or the username and +password for transmitting batches should be declared as attributes of the +Processor class, using the "has" operator. + +The external interface to the processor class is only two methods. + +- submit( B:BP::Batch ): Prepares and submits a batch of payment requests. + +- receive(): Returns any available batches of payment results from the + gateway. + +The base role provides default submit() and receive() methods that should +work in most cases. The recommended interface is to provide the following +methods: + +format_header( B:BP::Batch ): Creates the start of the formatted batch +(usually information such as your merchant account number and the date +of submission, and sometimes a sum or count of the items). This defaults +to an empty string. + +format_item( B:BP::Item, B:BP::Batch ): Takes a single payment request item, +and returns a string representing that item. This will be called for each +item in the batch, in order. See Business::BatchPayment::Item for the +attributes of the individual transactions. + +format_trailer( B:BP::Batch ): Creates the trailer for the request document. +This also defaults to an empty string. + +parse_batch_id( CONTENT ): Given a result document, extracts the batch ID +(as a string) and returns it. + +parse_item( LINE ): Given a single line of the result document, returns a +B:BP::Item (see perldoc there for details). This must contain "approved", +and either "tid" or both "customer_id" and "amount". + +default_transport: The default method for creating the B:BP::Transport object +for sending the request document to the gateway and retrieving results. If +the gateway uses HTTPS or SFTP in a straightforward way, you may be able +to use one of the existing transport classes (passing the hostname and +login credentials to the constructor). Otherwise, you may need to write +a transport class. See below. + +This is optional; if you don't provide a default transport, then the merchant +system using B:BP just has to provide one of its own. This is the recommended +way to deal with a batch upload that has to be done manually. + +default_on_error: The exception handler for format_item or parse_item. +Called with two arguments: the B:BP::Item object or data row, and the +die() string. This is optional, and can be overridden by the on_format_error +and on_parse_error attributes. + + +If the gateway's batch format doesn't lend itself to a simple +header/items/trailer division, you may need to override the higher-level +methods: + +format_request( B:BP::Batch ): Converts the entire batch to the format +expected by the gateway. (By default this simply calls the above methods.) + +parse_response( CONTENT ): Converts the entire reply document received from +the gateway to a B:BP::Batch object. As above, each reply item must contain +"approved", and either "tid" or both "customer_id" and "amount". + +B:BP::Transport class +--------------------- + +This must implement two methods, "upload" and "download". + +"upload" takes the batch content produced by format_request as an argument, +and does whatever is necessary to send it to the gateway. "download" takes +no arguments, and returns a list of strings containing batch results. + +The "SFTP", "HTTPS", and "File" subclasses all have "upload" and "download" +methods which may be suitable, but if not, they also expose access to their +protocols. For example, if the file needs to be compressed before being +submitted by SFTP, you could create a B:BP::Transport::SFTP subclass which +provides an "upload" method. That method would compress the file and then +call "$self->put" to send it to the host and path defined in the transport's +attributes. + +B:BP::TestMode +-------------- + +Include this role in your Processor module if it supports a test mode. +It will create a "test_mode" attribute which can be set to true; the processor +or transport should check this attribute, and do whatever is necessary to +enable test mode (submitting to a different server, setting a flag within +the request itself, etc.). + +If the processor doesn't have a test mode (or enables it on a per-account +basis, i.e. test mode is selected by using a test login), then don't include +this role, and attempts to set test_mode will simply fail. + +