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

NAME

FS::pay_batch - Object methods for pay_batch records

SYNOPSIS

 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;

DESCRIPTION

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.

METHODS

new HASHREF

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.

insert

Adds this record to the database. If there is an error, returns the error, otherwise returns false.

delete

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.

check

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.

agent

Returns the FS::agent object for this batch.

cust_pay_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.

try_to_resolve

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_for_export

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)

BUGS

status is somewhat redundant now that download and upload exist

SEE ALSO

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