FS::cust_main::Billing_Realtime - Realtime billing mixin for cust_main
These methods are available on FS::cust_main objects.
Attempt to collect the customer's current balance with a realtime credit card or electronic check 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 or ECHECK. 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
Runs a realtime credit card or ACH (electronic check) transaction via a Business::OnlinePayment realtime gateway. See http://420.am/business-onlinepayment for supported gateways.
Required arguments in the hashref are amount and either cust_payby or method, payinfo and (as applicable for method) payname, address1, address2, city, state, zip and paydate.
Available methods are: CC, ECHECK, or PAYPAL
Available optional arguments are: description, invnum, apply, quiet, paynum_ref, payunique, session_id
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.
no_invnum can be set to true to prevent that default invnum from being set.
apply can be set to true to run apply_payments_and_credits on success.
no_auto_apply can be set to true to set that flag on the resulting payment (prevents payment from being applied by apply_payments or apply_payments_and_credits, but will still be applied if invnum exists...use with no_invnum for intended effect.)
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)
Verifies successful third party processing of a realtime credit card or ACH (electronic check) 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.
DEPRECATED -- use agent->payment_gateway
Refunds a realtime credit card or ACH (electronic check) transaction via a Business::OnlinePayment realtime gateway. See http://420.am/business-onlinepayment for supported gateways.
Available methods are: CC or ECHECK
Available options are: amount, reasonnum, 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.
reasonnum specified an existing refund 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.
#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.
#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.
Runs an authorization-only transaction for $1 against this credit card (if successful, immediatly reverses the authorization).
Returns the empty string if the authorization was sucessful, or an error message otherwise.
Option cust_payby should be passed, even if it's not yet been inserted. Object will be tokenized if possible, but that change will not be updated in database (must be inserted/replaced afterwards.)
Currently only succeeds for Business::OnlinePayment CC transactions.
If possible and necessary, runs a tokenize transaction. In order to be possible, a credit card cust_payby record must be passed and a Business::OnlinePayment gateway capable of Tokenize transactions must be configured for this user. Is only necessary if payinfo is not yet tokenized.
Returns the empty string if the authorization was sucessful or was not possible/necessary (thus allowing this to be safely called with non-tokenizable records/gateways, without having to perform separate tests), or an error message otherwise.
Option cust_payby may be passed, even if it's not yet been inserted. Object will be tokenized if possible, but that change will not be updated in database (must be inserted/replaced afterwards.)
Otherwise, options method, payinfo and other cust_payby fields may be passed. If options are passed as a hashref, payinfo will be updated as appropriate in the passed hashref.
Can be run as a class method if option payment_gateway is passed, but default customer id/name/phone can't be set in that case. This is really only intended for tokenizing old records on upgrade.
Convenience wrapper for "tokenized" in FS::payinfo_Mixin
PAYINFO is required.
Can be run as class or object method, never loads from object.
NOT A METHOD. Acts on all customers. Placed here because it makes use of module-internal methods, and to keep everything that uses Billing::OnlinePayment all in one place.
Tokenizes all tokenizable card numbers from payinfo in cust_payby and CARD transactions in cust_pay_pending, cust_pay, cust_pay_void and cust_refund.
If the queue flag is set, newly tokenized records will be immediately committed, regardless of AutoCommit, so as to release the mutex on the record.
If all configured gateways have the ability to tokenize, detection of an untokenizable record will cause a fatal error. However, if the queue flag is set, this will instead cause a critical error to be recorded in the log, and any other tokenizable records will still be committed.
If the daily flag is also set, detection of existing untokenized records will record an info message in the system log (because they should have never appeared in the first place.) Tokenization will still be attempted.
If any configured gateways do NOT have the ability to tokenize, or if a default gateway is not configured, then untokenized records are not considered a threat, and no critical errors will be generated in the log.