Difference between revisions of "Freeside:3:Documentation:Developer/FS/cust main/Billing Realtime"

Latest revision as of 10:07, 10 April 2015

NAME

FS::cust_main::Billing_Realtime - Realtime billing mixin for cust_main

SYNOPSIS

DESCRIPTION

These methods are available on FS::cust_main objects.

METHODS

realtime_collect [ OPTION => VALUE ... ]

Attempt to collect the customer's current balance with a realtime credit card, electronic check, or phone bill transaction (see realtime_bop() below).

Returns the result of realtime_bop(): nothing, an error message, or a hashref of state information for a third-party transaction.

Available options are: method, amount, description, invnum, quiet, paynum_ref, payunique, session_id, pkgnum

method is one of: CC, ECHECK and LEC. If none is specified then it is deduced from the customer record.

If no amount is specified, then the customer balance is used.

The additional options payname, address1, address2, city, state, zip, payinfo and paydate are also available. Any of these options, if set, will override the value from the customer record.

description is a free-text field passed to the gateway. It defaults to the value defined by the business-onlinepayment-description configuration option, or "Internet services" if that is unset.

If an invnum is specified, this payment (if successful) is applied to the specified invoice.

apply will automatically apply a resulting payment.

quiet can be set true to suppress email decline notices.

paynum_ref can be set to a scalar reference. It will be filled in with the resulting paynum, if any.

payunique is a unique identifier for this payment.

session_id is a session identifier associated with this payment.

depend_jobnum allows payment capture to unlock export jobs

realtime_bop { [ ARG => VALUE ... ] }

Runs a realtime credit card, ACH (electronic check) or phone bill transaction via a Business::OnlinePayment realtime gateway. See http://420.am/business-onlinepayment for supported gateways.

Required arguments in the hashref are method, and amount

Available methods are: CC, ECHECK, LEC, and PAYPAL

Available optional arguments are: description, invnum, apply, quiet, paynum_ref, payunique, session_id

The additional options payname, address1, address2, city, state, zip, payinfo and paydate are also available. Any of these options, if set, will override the value from the customer record.

description is a free-text field passed to the gateway. It defaults to the value defined by the business-onlinepayment-description configuration option, or "Internet services" if that is unset.

If an invnum is specified, this payment (if successful) is applied to the specified invoice. If the customer has exactly one open invoice, that invoice number will be assumed. If you don't specify an invnum you might want to call the apply_payments method or set the apply option.

apply can be set to true to apply a resulting payment.

quiet can be set true to surpress email decline notices.

paynum_ref can be set to a scalar reference. It will be filled in with the resulting paynum, if any.

payunique is a unique identifier for this payment.

session_id is a session identifier associated with this payment.

depend_jobnum allows payment capture to unlock export jobs

discount_term attempts to take a discount by prepaying for discount_term. The payment will fail if amount is incorrect for this discount term.

A direct (Business::OnlinePayment) transaction will return nothing on success, or an error message on failure.

A third-party transaction will return a hashref containing:

- popup_url: the URL to which a browser should be redirected to complete the transaction. - collectitems: an arrayref of name-value pairs to be posted to popup_url. - reference: a reference ID for the transaction, to show the customer.

(moved from cust_bill) (probably should get realtime_{card,ach,lec} here too)

fake_bop; realtime_botpp_capture CUST_PAY_PENDING [ OPTION => VALUE ... ]

Verifies successful third party processing of a realtime credit card, ACH (electronic check) or phone bill transaction via a Business::OnlineThirdPartyPayment realtime gateway. See http://420.am/business-onlinethirdpartypayment for supported gateways.

Available options are: description, invnum, quiet, paynum_ref, payunique

The additional options payname, city, state, zip, payinfo and paydate are also available. Any of these options, if set, will override the value from the customer record.

description is a free-text field passed to the gateway. It defaults to "Internet services".

If an invnum is specified, this payment (if successful) is applied to the specified invoice. If you don't specify an invnum you might want to call the apply_payments method.

quiet can be set true to surpress email decline notices.

paynum_ref can be set to a scalar reference. It will be filled in with the resulting paynum, if any.

payunique is a unique identifier for this payment.

Returns a hashref containing elements bill_error (which will be undefined upon success) and session_id of any associated session.

default_payment_gateway

DEPRECATED -- use agent->payment_gateway

realtime_refund_bop METHOD [ OPTION => VALUE ... ]

Refunds a realtime credit card, ACH (electronic check) or phone bill transaction via a Business::OnlinePayment realtime gateway. See http://420.am/business-onlinepayment for supported gateways.

Available methods are: CC, ECHECK and LEC

Available options are: amount, reason, paynum, paydate

Most gateways require a reference to an original payment transaction to refund, so you probably need to specify a paynum.

amount defaults to the original amount of the payment if not specified.

reason specifies a reason for the refund.

paydate specifies the expiration date for a credit card overriding the value from the customer record or the payment record. Specified as yyyy-mm-dd

Implementation note: If amount is unspecified or equal to the amount of the orignal payment, first an attempt is made to "void" the transaction via the gateway (to cancel a not-yet settled transaction) and then if that fails, the normal attempt is made to "refund" ("credit") the transaction via the gateway is attempted. No attempt to "void" the transaction is made if the gateway has introspection data and doesn't support void.

1. The additional options payname, address1, address2, city, state, #zip, payinfo and paydate are also available. Any of these options, #if set, will override the value from the customer record.

1. If an invnum is specified, this payment (if successful) is applied to the #specified invoice. If you don't specify an invnum you might want to #call the apply_payments method.

BUGS

Not autoloaded.

SEE ALSO

FS::cust_main, FS::cust_main::Billing