CRM_Core_Payment
class CRM_Core_Payment
Class CRM_Core_Payment.
This class is the main class for the payment processor subsystem.
It is the parent class for payment processors. It also holds some IPN related functions that need to be moved. In particular handlePaymentMethod should be moved to a factory class.
Constants
BILLING_MODE_FORM |
How are we getting billing information. We are trying to completely deprecate these parameters. FORM - we collect it on the same page BUTTON - the processor collects it and sends it back to us via some protocol |
BILLING_MODE_BUTTON |
How are we getting billing information. We are trying to completely deprecate these parameters. FORM - we collect it on the same page BUTTON - the processor collects it and sends it back to us via some protocol |
BILLING_MODE_NOTIFY |
How are we getting billing information. We are trying to completely deprecate these parameters. FORM - we collect it on the same page BUTTON - the processor collects it and sends it back to us via some protocol |
PAYMENT_TYPE_CREDIT_CARD |
Which payment type(s) are we using? credit card direct debit or both |
PAYMENT_TYPE_DIRECT_DEBIT |
Which payment type(s) are we using? credit card direct debit or both |
RECURRING_PAYMENT_START |
Subscription / Recurring payment Status START, END |
RECURRING_PAYMENT_END |
Subscription / Recurring payment Status START, END |
Properties
protected string | $_component | Component - ie. event or contribute. | |
protected | $_paymentProcessor | ||
protected string | $baseReturnUrl | Base url of the calling form (offsite processors). | |
protected string | $successUrl | Return url upon success (offsite processors). | |
protected string | $cancelUrl | Return url upon failure (offsite processors). | |
protected int|string | $billingProfile | The profile configured to show on the billing form. | |
protected int | $paymentInstrumentID | Payment instrument ID. | |
protected bool | $backOffice | Is this a back office transaction. |
Methods
No description
Set back office property.
Get payment instrument id.
Set payment Instrument id.
Set base return path (offsite processors).
Set success return URL (offsite processors).
Set cancel return URL (offsite processors).
Set the configured payment profile.
Opportunity for the payment processor to override the entire form build.
Log payment notification message to forensic system log.
Check if capability is supported.
Are back office payments supported.
Can more than one transaction be processed at once?
Are live payments supported - e.g dummy doesn't support this.
Are test payments supported.
Should the first payment date be configurable when setting up back office recurring payments.
Does this processor support cancelling recurring contributions through code.
Does this processor support pre-approval.
Can recurring contributions be set against pledges.
Function to action pre-approval if supported
Get any details that may be available to the payment processor due to an approval process having happened.
Default payment instrument validation.
Getter for the payment processor.
Setter for the payment processor.
Setter for the payment form that wants to use the processor.
Get help text information (help, description, etc.) about this payment, to display to the user.
Getter for accessing member vars.
Get name for the payment information type.
Get label for the payment information type.
Get array of fields that should be displayed on the payment form.
Get an array of the fields that can be edited on the recurring contribution.
Get the help text to present on the recurring update page.
Get the metadata for all required fields.
Get the metadata of all the fields configured for this processor.
Get array of fields that should be displayed on the payment form for credit cards.
Get array of fields that should be displayed on the payment form for direct debits.
Return an array of all the details about the fields potentially required for payment fields.
Get billing fields required for this processor.
Get form metadata for billing address fields.
Get base url dependent on component.
Get url to return to after cancelled or failed transaction.
Get URL to return the browser to on success.
Get URL to return the browser to on failure.
Get URl for when the back button is pressed.
Get the notify (aka ipn, web hook or silent post) url.
Calling this from outside the payment subsystem is deprecated - use doPayment.
Process payment - this function wraps around both doTransferPayment and doDirectPayment.
Query payment processor for details about a transaction.
This function checks to see if we have the right config values.
Redirect for paypal.
Handle incoming payment notification.
Payment callback handler.
Check whether a method is present ( & supported ) by the payment processor object.
Some processors replace the form submit button with their own.
Checks to see if invoice_id already exists in db.
Get url for users to manage this recurring contribution for this processor.
Get description of payment to pass to processor.
Checks if backoffice recurring edit is allowed
Should a receipt be sent out for a pending payment.
Details
at line 141
bool
isBackOffice()
at line 150
setBackOffice(bool $isBackOffice)
Set back office property.
at line 159
int
getPaymentInstrumentID()
Get payment instrument id.
at line 170
setPaymentInstrumentID(int $paymentInstrumentID)
Set payment Instrument id.
By default we actually ignore the form value. The manual processor takes it more seriously.
at line 182
setBaseReturnUrl(string $url)
Set base return path (offsite processors).
This is only useful with an internal civicrm form.
at line 194
setSuccessUrl(string $url)
Set success return URL (offsite processors).
This overrides $baseReturnUrl
at line 206
setCancelUrl(string $url)
Set cancel return URL (offsite processors).
This overrides $baseReturnUrl
at line 215
setBillingProfile(int|string $value)
Set the configured payment profile.
at line 227
bool
buildForm(CRM_Core_Form $form)
Opportunity for the payment processor to override the entire form build.
at line 240
static mixed
logPaymentNotification(array $params)
Log payment notification message to forensic system log.
at line 265
bool
supports(string $capability)
Check if capability is supported.
Capabilities have a one to one relationship with capability-related functions on this class.
Payment processor classes should over-ride the capability-specific function rather than this one.
at line 283
protected bool
supportsBackOffice()
Are back office payments supported.
e.g paypal standard won't permit you to enter a credit card associated with someone else's login. The intention is to support off-site (other than paypal) & direct debit but that is not all working yet so to reach a 'stable' point we disable.
at line 301
protected bool
supportsMultipleConcurrentPayments()
Can more than one transaction be processed at once?
In general processors that process payment by server to server communication support this while others do not.
In future we are likely to hit an issue where this depends on whether a token already exists.
at line 315
protected bool
supportsLiveMode()
Are live payments supported - e.g dummy doesn't support this.
at line 324
protected bool
supportsTestMode()
Are test payments supported.
at line 335
protected bool
supportsFutureRecurStartDate()
Should the first payment date be configurable when setting up back office recurring payments.
We set this to false for historical consistency but in fact most new processors use tokens for recurring and can support this
at line 348
protected bool
supportsCancelRecurring()
Does this processor support cancelling recurring contributions through code.
If the processor returns true it must be possible to take action from within CiviCRM that will result in no further payments being processed. In the case of token processors (e.g IATS, eWay) updating the contribution_recur table is probably sufficient.
at line 363
protected bool
supportsPreApproval()
Does this processor support pre-approval.
This would generally look like a redirect to enter credentials which can then be used in a later payment call.
Currently Paypal express supports this, with a redirect to paypal after the 'Main' form is submitted in the contribution page. This token can then be processed at the confirm phase. Although this flow 'looks' like the 'notify' flow a key difference is that in the notify flow they don't have to return but in this flow they do.
at line 379
protected bool
supportsRecurContributionsForPledges()
Can recurring contributions be set against pledges.
In practice all processors that use the baseIPN function to finish transactions or call the completetransaction api support this by looking up previous contributions in the series and, if there is a prior contribution against a pledge, and the pledge is not complete, adding the new payment to the pledge.
However, only enabling for processors it has been tested against.
at line 393
doPreApproval(array $params)
Function to action pre-approval if supported
at line 405
array
getPreApprovalDetails(array $storedDetails)
Get any details that may be available to the payment processor due to an approval process having happened.
In some cases the browser is redirected to enter details on a processor site. Some details may be available as a result.
at line 418
validatePaymentInstrument(array $values, array $errors)
Default payment instrument validation.
Implement the usual Luhn algorithm via a static function in the CRM_Core_Payment_Form if it's a credit card Not a static function, because I need to check for payment_type.
at line 433
array
getPaymentProcessor()
Getter for the payment processor.
The payment processor array is based on the civicrm_payment_processor table entry.
at line 442
setPaymentProcessor(array $processor)
Setter for the payment processor.
at line 453
setForm(CRM_Core_Form $paymentForm)
deprecated
deprecated
Setter for the payment form that wants to use the processor.
at line 463
CRM_Core_Form
getForm()
deprecated
deprecated
Getter for payment form that is using the processor.
at line 482
string
getText(string $context, array $params)
Get help text information (help, description, etc.) about this payment, to display to the user.
at line 512
null
getVar(string $name)
Getter for accessing member vars.
at line 521
string
getPaymentTypeName()
Get name for the payment information type.
at line 530
string
getPaymentTypeLabel()
Get label for the payment information type.
at line 540
array
getPaymentFormFields()
Get array of fields that should be displayed on the payment form.
at line 572
array
getEditableRecurringScheduleFields()
Get an array of the fields that can be edited on the recurring contribution.
Some payment processors support editing the amount and other scheduling details of recurring payments, especially those which use tokens. Others are fixed. This function allows the processor to return an array of the fields that can be updated from the contribution recur edit screen.
The fields are likely to be a subset of these - 'amount', - 'installments', - 'frequency_interval', - 'frequency_unit', - 'cycle_day', - 'next_sched_contribution_date', - 'end_date', - 'failure_retry_day',
The form does not restrict which fields from the contribution_recur table can be added (although if the html_type metadata is not defined in the xml for the field it will cause an error.
Open question - would it make sense to return membership_id in this - which is sometimes editable and is on that form (UpdateSubscription).
at line 585
string
getRecurringScheduleUpdateHelpText()
Get the help text to present on the recurring update page.
This should reflect what can or cannot be edited.
at line 597
protected array;
getMandatoryFields()
Get the metadata for all required fields.
at line 612
protected array
getAllFields()
Get the metadata of all the fields configured for this processor.
at line 622
protected array
getCreditCardFormFields()
Get array of fields that should be displayed on the payment form for credit cards.
at line 636
protected array
getDirectDebitFormFields()
Get array of fields that should be displayed on the payment form for direct debits.
at line 653
array
getPaymentFormFieldsMetadata()
Return an array of all the details about the fields potentially required for payment fields.
Only those determined by getPaymentFormFields will actually be assigned to the form
at line 818
array
getBillingAddressFields(int $billingLocationID = NULL)
Get billing fields required for this processor.
We apply the existing default of returning fields only for payment processor type 1. Processors can override to alter.
at line 848
array
getBillingAddressFieldsMetadata(int $billingLocationID = NULL)
Get form metadata for billing address fields.
at line 962
protected string
getBaseReturnUrl()
Get base url dependent on component.
(or preferably set it using the setter function).
at line 983
string
getCancelUrl(string $qfKey, int $participantID)
Get url to return to after cancelled or failed transaction.
at line 1014
protected string
getReturnSuccessUrl($qfKey)
Get URL to return the browser to on success.
at line 1037
protected string
getReturnFailUrl(string $key, int $participantID = NULL, int $eventID = NULL)
Get URL to return the browser to on failure.
at line 1064
protected string
getGoBackUrl($qfKey)
Get URl for when the back button is pressed.
at line 1082
protected string
getNotifyUrl()
Get the notify (aka ipn, web hook or silent post) url.
If there is no '.' in it we assume that we are dealing with localhost or similar and it is unreachable from the web & hence invalid.
at line 1104
protected array
doDirectPayment(array $params)
Calling this from outside the payment subsystem is deprecated - use doPayment.
Does a server to server payment transaction.
at line 1133
array
doPayment(array $params, string $component = 'contribute')
Process payment - this function wraps around both doTransferPayment and doDirectPayment.
The function ensures an exception is thrown & moves some of this logic out of the form layer and makes the forms more agnostic.
Payment processors should set payment_status_id. This function adds some historical defaults ie. the assumption that if a 'doDirectPayment' processors comes back it completed the transaction & in fact doTransferCheckout would not traditionally come back.
doDirectPayment does not do an immediate payment for Authorize.net or Paypal so the default is assumed to be Pending.
Once this function is fully rolled out then it will be preferred for processors to throw exceptions than to return Error objects
at line 1183
array
doQuery(array $params)
Query payment processor for details about a transaction.
at line 1193
abstract protected string
checkConfig()
This function checks to see if we have the right config values.
at line 1204
static bool
paypalRedirect($paymentProcessor)
Redirect for paypal.
at line 1228
static
handleIPN()
Handle incoming payment notification.
IPNs, also called silent posts are notifications of payment outcomes or activity on an external site.
at line 1257
static
handlePaymentMethod(string $method, array $params = array())
Payment callback handler.
The processor_name or processor_id is passed in. Note that processor_id is more reliable as one site may have more than one instance of a processor & ideally the processor will be validating the results Load requested payment processor and call that processor's handle<$method> method
at line 1353
bool
isSupported(string $method)
deprecated
deprecated
Check whether a method is present ( & supported ) by the payment processor object.
at line 1364
isSuppressSubmitButtons()
Some processors replace the form submit button with their own.
Returning false here will leave the button off front end forms.
At this stage there is zero cross-over between back-office processors and processors that suppress the submit.
at line 1382
protected bool
checkDupe(int $invoiceId, null $contributionID = NULL)
Checks to see if invoice_id already exists in db.
It's arguable if this belongs in the payment subsystem at all but since several processors implement it it is better to standardise to being here.
at line 1400
string
subscriptionURL(int $entityID = NULL, null $entity = NULL, string $action = 'cancel')
Get url for users to manage this recurring contribution for this processor.
at line 1483
protected string
getPaymentDescription(array $params, int $length = 24)
Get description of payment to pass to processor.
This is often what people see in the interface so we want to get as much unique information in as possible within the field length (& presumably the early part of the field)
People seeing these can be assumed to be advanced users so quantity of information probably trumps having field names to clarify
at line 1503
bool
supportsEditRecurringContribution()
Checks if backoffice recurring edit is allowed
at line 1512
isSendReceiptForPending()
Should a receipt be sent out for a pending payment.
e.g for traditional pay later & ones with a delayed settlement a pending receipt makes sense.