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 20: Line 20:
 
An FS::pay_batch object represents an payment batch. FS::pay_batch inherits from FS::Record. The following fields are currently supported:
 
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 -; upload -
+
; 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==
 
==METHODS==
 
; new HASHREF
 
; new HASHREF
Line 35: Line 37:
 
: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.
 
: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
 
; agent
:Returns the [[Freeside:3:Documentation:Developer/FS/agent|FS::agent]] object for this template.
+
:Returns the [[Freeside:3:Documentation:Developer/FS/agent|FS::agent]] object for this batch.
 +
; cust_pay_batch
 +
:Returns all [[Freeside:3:Documentation:Developer/FS/cust pay batch|FS::cust_pay_batch]] objects for this batch.
 
; rebalance; set_status; import_results OPTION => VALUE, ...
 
; rebalance; set_status; import_results OPTION => VALUE, ...
 
:Import batch results.
 
:Import batch results.
Line 43: Line 47:
 
:''filehandle'' - open filehandle of results file.
 
:''filehandle'' - open filehandle of results file.
  
:''format'' - "csv-td_canada_trust-merchant_pc_batch", "csv-chase_canada-E-xactBatch", "ach-spiritone", or "PAP"
+
:''format'' - an [[Freeside:3:Documentation:Developer/FS/pay batch|FS::pay_batch]] module
 +
 
 +
:''gateway'' - an [[Freeside:3:Documentation:Developer/FS/payment gateway|FS::payment_gateway]] object for a batch gateway. This takes precedence over ''format''.
 +
; 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.
 +
 
 +
: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 [[Freeside:3:Documentation:Developer/FS/payment gateway|FS::payment_gateway]], required - filehandle: a file name or handle to use as a data source. - job: an [[Freeside:3:Documentation:Developer/FS/queue|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 [[Freeside:3:Documentation:Developer/FS/pay batch|FS::pay_batch]] module, in which case the configuration options are in 'batchconfig-FORMAT'.
 +
 
 +
:Alternatively, GATEWAY can be an [[Freeside:3:Documentation:Developer/FS/payment gateway|FS::payment_gateway]] object set to a [[Freeside:3:Documentation:Developer/Business/BatchPayment|Business::BatchPayment]] module.
 +
; export_to_gateway GATEWAY OPTIONS
 +
:Given [[Freeside:3:Documentation:Developer/FS/payment gateway|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==
 
==BUGS==

Revision as of 13:37, 27 June 2014

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