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

From Freeside
< Freeside:4:Documentation:Developer‎ | FS
Revision as of 07:20, 18 November 2015 by Jeremyd (talk | contribs) (Edit via perl MediaWiki framework (1.13))

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


FS::cust_pay - Object methods for cust_pay objects


 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;


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:

primary key (assigned automatically for new payments)
customer (see FS::cust_main)
specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.
Amount of this payment
order taker (see FS::access_user)
Payment Type (See FS::payinfo_Mixin for valid values)
Payment Information (See FS::payinfo_Mixin for data format)
Masked payinfo (See FS::payinfo_Mixin for how this works)
obsolete text field for tracking card processing or other batch grouping
Optional unique identifer to prevent duplicate transactions.
books closed flag, empty or `Y'
Desired pkgnum when using experimental package balances.
Flag to only allow manual application of payment, empty or 'Y'
The bank where the payment was deposited.
The name of the depositor.
The deposit account number.
The teller number.
The number of the batch this payment came from (see FS::pay_batch), or null if it was processed through a realtime gateway or entered manually.
The number of the realtime or batch gateway FS::payment_gateway) this payment was processed through. Null if it was entered manually or processed by the "system default" gateway, which doesn't have a number.
The name of the processor module (Business::OnlinePayment, ::BatchPayment, or ::OnlineThirdPartyPayment subclass) used for this payment. Slightly redundant with gatewaynum.
The authorization number returned by the credit card network.
The transaction ID returned by the gateway, if any. This is usually what you would use to initiate a void or refund of the payment.


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. The following arguments are supported:
If true, a payment receipt is sent instead of a statement when 'payment_receipt_email' configuration option is set.
About the "manual" flag: Normally, if the 'payment_receipt' config option is set, and the customer has an invoice email address, inserting a payment causes a statement to be emailed to the customer. If the payment is considered "manual" (or if the customer has no invoices), then it will instead send a payment receipt. "manual" should be true whenever a payment is created directly from the web interface, from a user-initiated realtime payment, or from a third-party payment via self-service. It should be false when creating a payment from a billing event or from a batch.
Don't send an email receipt. (Note: does not currently work when payment_receipt-trigger is set to something other than default / cust_bill)
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.
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.
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:
Flag indicating the payment is being made manually.
Invoice (FS::cust_bill) object. If not specified, the most recent invoice will be assumed.
Customer (FS::cust_main) object (for efficiency).
Don't send an email receipt.
Returns all applications to invoices (see FS::cust_bill_pay) for this payment.
Returns all applications of refunds (see FS::cust_pay_refund) to this payment.
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).
Returns the amount of this payment that has not been refuned; which is paid minus all refund applications (see FS::cust_pay_refund).
Returns the "paid" field.
delete_cust_bill_pay OPTIONS
Deletes all associated cust_bill_pay records.
If option 'unapplied' is a specified, only deletes until this object's 'unapplied' value is >= the specified amount. (Deletes in order returned by "cust_bill_pay".)
refund HASHREF
Accepts input for creating a new FS::cust_refund object. Unapplies payment from invoices up to the amount of the refund, creates the refund and applies payment to refund. Allows entire process to be handled in one transaction.
Causes a fatal error if called on CARD or CHEK payments.


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.

Returns an SQL fragment to retreive the unapplied amount.


process_batch_import; batch_import HASHREF
Inserts new payments.


Delete and replace methods.


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