Difference between revisions of "Freeside:3:Documentation:Developer/FS/pay batch"

From Freeside
Jump to: navigation, search
m (Edit via perl MediaWiki framework (1.13))
m (Edit via perl MediaWiki framework (1.13))
Line 50: Line 50:
  
 
:''gateway'' - an [[Freeside:3:Documentation:Developer/FS/payment gateway|FS::payment_gateway]] object for a batch gateway. This takes precedence over ''format''.
 
:''gateway'' - an [[Freeside:3:Documentation:Developer/FS/payment gateway|FS::payment_gateway]] object for a batch gateway. This takes precedence over ''format''.
 +
 +
: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_from_gateway [ OPTIONS ]
 
:Import results from a [[Freeside:3:Documentation:Developer/FS/payment gateway|FS::payment_gateway]], using Business::BatchPayment, and apply them. GATEWAY must use the Business::BatchPayment namespace.
 
:Import results from a [[Freeside:3:Documentation:Developer/FS/payment gateway|FS::payment_gateway]], using Business::BatchPayment, and apply them. GATEWAY must use the Business::BatchPayment namespace.

Revision as of 06:34, 24 March 2015

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