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.