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

From Freeside
Jump to: navigation, search
m (Edit via perl MediaWiki framework (1.13))
(No difference)

Revision as of 20:04, 27 June 2012

NAME

FS::cust_pay - Object methods for cust_pay objects

SYNOPSIS

 use FS::cust_pay;

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

 $error = $record->insert;

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

 $error = $record->delete;

 $error = $record->check;

DESCRIPTION

An FS::cust_pay object represents a payment; the transfer of money from a customer. FS::cust_pay inherits from FS::Record. The following fields are currently supported:

paynum
primary key (assigned automatically for new payments)
custnum
customer (see FS::cust_main)
_date
specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.
paid
Amount of this payment
usernum
order taker (see FS::access_user)
payby
Payment Type (See FS::payinfo_Mixin for valid values)
payinfo
Payment Information (See FS::payinfo_Mixin for data format)
paymask
Masked payinfo (See FS::payinfo_Mixin for how this works)
paybatch
text field for tracking card processing or other batch grouping
payunique
Optional unique identifer to prevent duplicate transactions.
closed
books closed flag, empty or `Y'
pkgnum
Desired pkgnum when using experimental package balances.
bank
The bank where the payment was deposited.
depositor
The name of the depositor.
account
The deposit account number.
teller
The teller number.

METHODS

new HASHREF
Creates a new payment. To add the payment to the databse, see "insert".
insert [ OPTION => VALUE ... ]
Adds this payment to the database.
For backwards-compatibility and convenience, if the additional field invnum is defined, an FS::cust_bill_pay record for the full amount of the payment will be created. In this case, custnum is optional.
If the additional field discount_term is defined then a prepayment discount is taken for that length of time. It is an error for the customer to owe after this payment is made.
A hash of optional arguments may be passed. Currently "manual" is supported. If true, a payment receipt is sent instead of a statement when 'payment_receipt_email' configuration option is set.
void [ REASON ]
Voids this payment: deletes the payment and all associated applications and adds a record of the voided payment to the FS::cust_pay_void table.
delete
Unless the closed flag is set, deletes this payment and all associated applications (see FS::cust_bill_pay and FS::cust_pay_refund). In most cases, you want to use the void method instead to leave a record of the deleted payment.
replace [ OLD_RECORD ]
You can, but probably shouldn't modify payments...
Replaces the OLD_RECORD with this one in the database, or, if OLD_RECORD is not supplied, replaces this record. If there is an error, returns the error, otherwise returns false.
check
Checks all fields to make sure this is a valid payment. If there is an error, returns the error, otherwise returns false. Called by the insert method.
send_receipt HASHREF | OPTION => VALUE ...
Sends a payment receipt for this payment..
Available options:
manual
Flag indicating the payment is being made manually.
cust_bill
Invoice (FS::cust_bill) object. If not specified, the most recent invoice will be assumed.
cust_main
Customer (FS::cust_main) object (for efficiency).
cust_bill_pay
Returns all applications to invoices (see FS::cust_bill_pay) for this payment.
cust_pay_refund
Returns all applications of refunds (see FS::cust_pay_refund) to this payment.
unapplied
Returns the amount of this payment that is still unapplied; which is paid minus all payment applications (see FS::cust_bill_pay) and refund applications (see FS::cust_pay_refund).
unrefunded
Returns the amount of this payment that has not been refuned; which is paid minus all refund applications (see FS::cust_pay_refund).
amount
Returns the "paid" field.

CLASS METHODS

batch_insert CUST_PAY_OBJECT, ...
Class method which inserts multiple payments. Takes a list of FS::cust_pay objects. Returns a list, each element representing the status of inserting the corresponding payment - empty. If there is an error inserting any payment, the entire transaction is rolled back, i.e. all payments are inserted or none are.
FS::cust_pay objects may have the pseudo-field 'apply_to', containing a reference to an array of (uninserted) FS::cust_bill_pay objects. If so, those objects will be inserted with the paynum of the payment, and for each one, an error message or an empty string will be inserted into the list of errors.
For example:

 my @errors = FS::cust_pay->batch_insert(@cust_pay);
 my $num_errors = scalar(grep $_, @errors);
 if ( $num_errors == 0 ) {
   #success; all payments were inserted
 } else {
   #failure; no payments were inserted.
 }

unapplied_sql
Returns an SQL fragment to retreive the unapplied amount.

SUBROUTINES

batch_import HASHREF
Inserts new payments.

BUGS

Delete and replace methods.

SEE ALSO

FS::cust_pay_pending, FS::cust_bill_pay, FS::cust_bill, FS::Record, schema.html from the base documentation.