Freeside:4:Documentation:Developer/FS/pay batch

From Freeside
Jump to: navigation, search


FS::pay_batch - Object methods for pay_batch records


 use FS::pay_batch;

 $record = new FS::pay_batch \%hash;
 $record = new FS::pay_batch { 'column' => 'value' };

 $error = $record->insert;

 $error = $new_record->replace($old_record);

 $error = $record->delete;

 $error = $record->check;


An FS::pay_batch object represents an payment batch. FS::pay_batch inherits from FS::Record. The following fields are currently supported:

batchnum - primary key; agentnum - optional agent number for agent batches; payby - CARD or CHEK; status - O (Open), I (In-transit), or R (Resolved); download - time when the batch was first downloaded; upload - time when the batch was first uploaded; title - unique batch identifier
For incoming batches, the combination of 'title', 'payby', and 'agentnum' must be unique.


Creates a new batch. To add the batch to the database, see "insert".
Note that this stores the hash reference, not a distinct copy of the hash it points to. You can ask the object for a copy with the hash method.
Adds this record to the database. If there is an error, returns the error, otherwise returns false.
Delete this record from the database.
replace OLD_RECORD
Replaces the OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.
Checks all fields to make sure this is a valid batch. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.
Returns the FS::agent object for this batch.
Returns all FS::cust_pay_batch objects for this batch.
rebalance; set_status; import_results OPTION => VALUE, ...
Import batch results. Can be called as an instance method, if you want to automatically adjust status on a specific batch, or a class method, if you don't know which batch(es) the results apply to.
Options are:
filehandle - open filehandle of results file.
format - an FS::pay_batch module
gateway - an FS::payment_gateway object for a batch gateway. This takes precedence over format.
no_close - do not try to close batches
Supported format keys (defined in the specified FS::pay_batch module) are:
filetype - required, can be CSV, fixed, variable, XML
fields - required list of field names for each row/line
formatre - regular expression for fixed filetype
parse - required for variable filetype
xmlkeys - required for XML filetype
xmlrow - required for XML filetype
begin_condition - sub, ignore all lines before this returns true
end_condition - sub, stop processing lines when this returns true
end_hook - sub, runs immediately after end_condition returns true
skip_condition - sub, skip lines when this returns true
hook - required, sub, runs before approved/declined conditions are checked
approved - required, sub, returns true when approved
declined - required, sub, returns true when declined
close_condition - sub, decide whether or not to close the batch
import_from_gateway [ OPTIONS ]
Import results from a FS::payment_gateway, using Business::BatchPayment, and apply them. GATEWAY must use the Business::BatchPayment namespace.
This is a class method, since results can be applied to any batch. The 'batch-reconsider' option determines whether an already-approved or declined payment can have its status changed by a later import.
OPTIONS may include:
- gateway: the FS::payment_gateway, required - filehandle: a file name or handle to use as a data source. - job: an FS::queue object to update with progress messages.
Resolve this batch if possible. A batch can be resolved if all of its entries have status. If the system options 'batch-auto_resolve_days' and 'batch-auto_resolve_status' are set, and the batch's download date is at least (batch-auto_resolve_days) before the current time, then it can be auto-resolved; entries with no status will be approved or declined according to the batch-auto_resolve_status setting.
Prepare the batch to be exported. This will: - Set the status to "in transit". - If batch-increment_expiration is set and this is a credit card batch, increment expiration dates that are in the past. - If this is the first download for this batch, adjust payment amounts to not be greater than the customer's current balance. If the customer's balance is zero, the entry will be removed.
Use this within a transaction.
export_batch [ format => FORMAT | gateway => GATEWAY ]
Export batch for processing. FORMAT is the name of an FS::pay_batch module, in which case the configuration options are in 'batchconfig-FORMAT'.
Alternatively, GATEWAY can be an FS::payment_gateway object set to a Business::BatchPayment module.
export_to_gateway GATEWAY OPTIONS
Given FS::payment_gateway GATEWAY, export the items in this batch to that gateway via Business::BatchPayment. OPTIONS may include:
- file: override the default transport and write to this file (name or handle)


status is somewhat redundant now that download and upload exist


FS::Record, schema.html from the base documentation.