Documentation

PaymentProcessorWithStandardBillingRequirements extends CRM_Core_Payment
in package

Application

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_BUTTON = 2: How are we getting billing information.
BILLING_MODE_FORM = 1: How are we getting billing information.
BILLING_MODE_NOTIFY = 4: How are we getting billing information.
PAYMENT_TYPE_CREDIT_CARD = 1: Which payment type(s) are we using?
PAYMENT_TYPE_DIRECT_DEBIT = 2: Which payment type(s) are we using?
RECURRING_PAYMENT_END = 'END': Subscription / Recurring payment Status START, END
RECURRING_PAYMENT_START = 'START': Subscription / Recurring payment Status START, END

Properties

$_processorName : string: Processor type label.
$_component : string: Component - ie. event or contribute.
$_paymentProcessor : array<string|int, mixed>
$backOffice : bool: Is this a back office transaction.
$baseReturnUrl : string: Base url of the calling form (offsite processors).
$billingProfile : int|string: The profile configured to show on the billing form.
$cancelUrl : string: Return url upon failure (offsite processors).
$paymentInstrumentID : int: Payment instrument ID.
$propertyBag : PropertyBag: This is only needed during the transitional phase. In future you should pass your own PropertyBag into the method you're calling.
$successUrl : string: Return url upon success (offsite processors).

Methods

__construct() : mixed: Constructor.
buildForm() : bool: Opportunity for the payment processor to override the entire form build.
checkConfig() : string: again, `checkConfig` is abstract in CRM_Core_Payment, so we are forced to implement it
doCancelRecurring() : array<string|int, mixed>: Cancel a recurring subscription.
doPayment() : array<string|int, mixed>: Process payment - this function wraps around both doTransferCheckout and doDirectPayment.
doPreApproval() : mixed: Function to action pre-approval if supported
doQuery() : array<string|int, mixed>: Query payment processor for details about a transaction.
doRefund() : array<string|int, mixed>: Refunds payment
extractCustomPropertiesForDoPayment() : mixed: Processors may need to inspect, validate, cast and copy data that is specific to this Payment Processor from the input array to custom fields on the PropertyBag.
getBillingAddressFields() : array<string|int, mixed>: Get billing fields required for this processor.
getBillingAddressFieldsMetadata() : array<string|int, mixed>: Get form metadata for billing address fields.
getCancelUrl() : string: Get url to return to after cancelled or failed transaction.
getEditableRecurringScheduleFields() : array<string|int, mixed>: Get an array of the fields that can be edited on the recurring contribution.
getForm() : CRM_Core_Form: Getter for payment form that is using the processor.
getID() : int: Getter for the id Payment Processor ID.
getPaymentFormFields() : array<string|int, mixed>: Get array of fields that should be displayed on the payment form.
getPaymentFormFieldsMetadata() : array<string|int, mixed>: Return an array of all the details about the fields potentially required for payment fields.
getPaymentInstrumentID() : int: Return the payment instrument ID to use.
getPaymentProcessor() : array<string|int, mixed>: Getter for the payment processor.
getPaymentTypeLabel() : string: Get label for the payment information type.
getPaymentTypeName() : string: Get name for the payment information type.
getPreApprovalDetails() : array<string|int, mixed>: Get any details that may be available to the payment processor due to an approval process having happened.
getRecurringScheduleUpdateHelpText() : string: Get the help text to present on the recurring update page.
getText() : string: Get help text information (help, description, etc.) about this payment, to display to the user.
getTitle() : string: Get the title of the payment processor to display to the user
getVar() : null: Getter for accessing member vars.
handleIPN() : mixed: Handle incoming payment notification.
handlePaymentMethod() : mixed: Payment callback handler.
isBackOffice() : bool
isSendReceiptForPending() : mixed: Should a receipt be sent out for a pending payment.
isSupported() : bool: Check whether a method is present ( & supported ) by the payment processor object.
isSuppressSubmitButtons() : mixed: Some processors replace the form submit button with their own.
logPaymentNotification() : mixed: Log payment notification message to forensic system log.
paypalRedirect() : bool: Redirect for paypal.
setBackOffice() : mixed: Set back office property.
setBaseReturnUrl() : mixed: Set base return path (offsite processors).
setBillingProfile() : mixed: Set the configured payment profile.
setCancelUrl() : mixed: Set cancel return URL (offsite processors).
setForm() : mixed: Setter for the payment form that wants to use the processor.
setPaymentInstrumentID() : mixed
setPaymentProcessor() : mixed: Setter for the payment processor.
setSuccessUrl() : mixed: Set success return URL (offsite processors).
subscriptionURL() : string|null: Get url for users to manage this recurring contribution for this processor.
supports() : bool: Check if capability is supported.
supportsEditRecurringContribution() : bool: Checks if back-office recurring edit is allowed
supportsNoReturn() : bool: Checks if payment processor supports not returning to the form processing.
supportsNoReturnForRecurring() : bool: Checks if payment processor supports not returning to the form processing on recurring.
supportsRecurring() : bool: Checks if payment processor supports recurring contributions
supportsRefund() : bool: Does this payment processor support refund?
validatePaymentInstrument() : mixed: Default payment instrument validation.
checkDupe() : bool: Checks to see if invoice_id already exists in db.
doDirectPayment() : array<string|int, mixed>: Calling this from outside the payment subsystem is deprecated - use doPayment.
doTransferCheckout() : array<string|int, mixed>: Calling this from outside the payment subsystem is deprecated - use doPayment.
getAllFields() : array<string|int, mixed>: Get the metadata of all the fields configured for this processor.
getAmount() : string: Get the submitted amount, padded to 2 decimal places, if needed.
getBaseReturnUrl() : string: Get base url dependent on component.
getCreditCardFormFields() : array<string|int, mixed>: Get array of fields that should be displayed on the payment form for credit cards.
getCurrency() : string: Get the currency for the transaction from the params.
getDirectDebitFormFields() : array<string|int, mixed>: Get array of fields that should be displayed on the payment form for direct debits.
getGoBackUrl() : string: Get URl for when the back button is pressed.
getMandatoryFields() : mixed: Get the metadata for all required fields.
getNotifyUrl() : string: Get the notify (aka ipn, web hook or silent post) url.
getPaymentDescription() : string: Get description of payment to pass to processor.
getReturnFailUrl() : string: Get URL to return the browser to on failure.
getReturnSuccessUrl() : string: Get URL to return the browser to on success.
setStatusPaymentCompleted() : array<string|int, mixed>: Set the payment status to Completed
setStatusPaymentPending() : array<string|int, mixed>: Set the payment status to Pending
supportsAccountLoginURL() : bool: Checks if payment processor supports an account login URL TODO: This is checked by self::subscriptionURL but is only used if no entityID is found.
supportsBackOffice() : bool: Are back office payments supported.
supportsCancelRecurring() : bool: Does this processor support cancelling recurring contributions through code.
supportsCancelRecurringNotifyOptional() : bool: Does the processor support the user having a choice as to whether to cancel the recurring with the processor?
supportsChangeSubscriptionAmount() : bool: Does this processor support changing the amount for recurring contributions through code.
supportsFutureRecurStartDate() : bool: Should the first payment date be configurable when setting up back office recurring payments.
supportsLiveMode() : bool: Are live payments supported - e.g dummy doesn't support this.
supportsMultipleConcurrentPayments() : bool: Can more than one transaction be processed at once?
supportsNoEmailProvided() : bool: Does the processor work without an email address?
supportsPreApproval() : bool: Does this processor support pre-approval.
supportsRecurContributionsForPledges() : bool: Can recurring contributions be set against pledges.
supportsTestMode() : bool: Are test payments supported.
supportsUpdateSubscriptionBillingInfo() : bool: Does this processor support updating billing info for recurring contributions through code.

BILLING_MODE_BUTTON

How are we getting billing information.


    public
        mixed
    BILLING_MODE_BUTTON
    = 2

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_FORM

How are we getting billing information.


    public
        mixed
    BILLING_MODE_FORM
    = 1

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.


    public
        mixed
    BILLING_MODE_NOTIFY
    = 4

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?


    public
        mixed
    PAYMENT_TYPE_CREDIT_CARD
    = 1

credit card direct debit or both

PAYMENT_TYPE_DIRECT_DEBIT

Which payment type(s) are we using?


    public
        mixed
    PAYMENT_TYPE_DIRECT_DEBIT
    = 2

credit card direct debit or both

RECURRING_PAYMENT_END

Subscription / Recurring payment Status START, END


    public
        mixed
    RECURRING_PAYMENT_END
    = 'END'

RECURRING_PAYMENT_START

Subscription / Recurring payment Status START, END


    public
        mixed
    RECURRING_PAYMENT_START
    = 'START'

$_processorName

Processor type label.


    public
        string
    $_processorName

(Deprecated unused parameter).

$_component

Component - ie. event or contribute.


    protected
        string
    $_component

This is used for setting return urls.

$_paymentProcessor


    protected
        array<string|int, mixed>
    $_paymentProcessor

$backOffice

Is this a back office transaction.


    protected
        bool
    $backOffice
     = \FALSE

$baseReturnUrl

Base url of the calling form (offsite processors).


    protected
        string
    $baseReturnUrl

$billingProfile

The profile configured to show on the billing form.


    protected
        int|string
    $billingProfile

Currently only the pseudo-profile 'billing' is supported but hopefully in time we will take an id and load that from the DB and the processor will be able to return a set of fields that combines it's minimum requirements with the configured requirements.

Currently only the pseudo-processor 'manual' or 'pay-later' uses this setting to return a 'curated' set of fields.

Note this change would probably include converting 'billing' to a reserved profile.

$cancelUrl

Return url upon failure (offsite processors).


    protected
        string
    $cancelUrl

$paymentInstrumentID

Payment instrument ID.


    protected
        int
    $paymentInstrumentID

This is normally retrieved from the payment_processor table.

$propertyBag

This is only needed during the transitional phase. In future you should pass your own PropertyBag into the method you're calling.


    protected
        PropertyBag
    $propertyBag

New code should NOT use $this->propertyBag.

$successUrl

Return url upon success (offsite processors).


    protected
        string
    $successUrl

__construct()

Constructor.


    public
                    __construct() : mixed

buildForm()

Opportunity for the payment processor to override the entire form build.


    public
                    buildForm(CRM_Core_Form &$form) : bool

Parameters

$form : CRM_Core_Form

Return values

bool —

Should form building stop at this point?

checkConfig()

again, `checkConfig` is abstract in CRM_Core_Payment, so we are forced to implement it


    public
                    checkConfig() : string

Return values

string —

the error message if any

doCancelRecurring()

Cancel a recurring subscription.


    public
                    doCancelRecurring(PropertyBag $propertyBag) : array<string|int, mixed>

Payment processor classes should override this rather than implementing cancelSubscription.

A PaymentProcessorException should be thrown if the update of the contribution_recur record should not proceed (in many cases this function does nothing as the payment processor does not need to take any action & this should silently proceed. Note the form layer will only call this after calling $processor->supports('cancelRecurring');

A payment processor can control whether to notify the actual payment provider or just cancel in CiviCRM by setting the isNotifyProcessorOnCancelRecur property on PropertyBag. If supportsCancelRecurringNotifyOptional() is TRUE this will be automatically set based on the user selection on the form. If FALSE you need to set it yourself.

Parameters

$propertyBag : PropertyBag

Return values

array<string|int, mixed>

doPayment()

Process payment - this function wraps around both doTransferCheckout and doDirectPayment.


    public
                    doPayment(array<string|int, mixed>|PropertyBag &$params[, string $component = 'contribute' ]) : array<string|int, mixed>

Any processor that still implements the deprecated doTransferCheckout() or doDirectPayment() should be updated to use doPayment().

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. Payment processors should throw exceptions and not return Error objects as they may have done with the old functions.

Payment processors should set payment_status_id (which is really contribution_status_id) in the returned array. The default is assumed to be Pending. In some cases the IPN will set the payment to "Completed" some time later.

Parameters

$params : array<string|int, mixed>|PropertyBag
$component : string = 'contribute'

Return values

array<string|int, mixed> —

Result array (containing at least the key payment_status_id)

doPreApproval()

Function to action pre-approval if supported


    public
                    doPreApproval(array<string|int, mixed> &$params) : mixed

Parameters

$params : array<string|int, mixed>

Parameters from the form

This function returns an array which should contain

pre_approval_parameters (this will be stored on the calling form & available later)
redirect_url (if set the browser will be redirected to this.

doQuery()

Query payment processor for details about a transaction.


    public
                    doQuery(array<string|int, mixed> $params) : array<string|int, mixed>

Parameters

$params : array<string|int, mixed>

Array of parameters containing one of:

trxn_id Id of an individual transaction.
processor_id Id of a recurring contribution series as stored in the civicrm_contribution_recur table.

Return values

array<string|int, mixed> —

Extra parameters retrieved. Any parameters retrievable through this should be documented in the function comments at CRM_Core_Payment::doQuery. Currently:

fee_amount Amount of fee paid

doRefund()

Refunds payment


    public
                    doRefund(array<string|int, mixed> &$params) : array<string|int, mixed>

Parameters

$params : array<string|int, mixed>

Return values

array<string|int, mixed> —

Result array (containing at least the key refund_status)

extractCustomPropertiesForDoPayment()

Processors may need to inspect, validate, cast and copy data that is specific to this Payment Processor from the input array to custom fields on the PropertyBag.


    public
                    extractCustomPropertiesForDoPayment(PropertyBag $propertyBag, array<string|int, mixed> $params[, string $component = 'contribute' ]) : mixed

Parameters

$propertyBag : PropertyBag
$params : array<string|int, mixed>
$component : string = 'contribute'

getBillingAddressFields()

Get billing fields required for this processor.


    public
                    getBillingAddressFields([int $billingLocationID = NULL ]) : array<string|int, mixed>

We apply the existing default of returning fields only for payment processor type 1. Processors can override to alter.

Parameters

$billingLocationID : int = NULL

Return values

array<string|int, mixed>

getBillingAddressFieldsMetadata()

Get form metadata for billing address fields.


    public
                    getBillingAddressFieldsMetadata([int $billingLocationID = NULL ]) : array<string|int, mixed>

Parameters

$billingLocationID : int = NULL

Return values

array<string|int, mixed> —

Array of metadata for address fields.

getCancelUrl()

Get url to return to after cancelled or failed transaction.


    public
                    getCancelUrl(string $qfKey[, int|null $participantID = NULL ]) : string

Parameters

$qfKey : string
$participantID : int|null = NULL

Return values

string —

cancel url

getEditableRecurringScheduleFields()

Get an array of the fields that can be edited on the recurring contribution.


    public
                    getEditableRecurringScheduleFields() : array<string|int, mixed>

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).

Return values

array<string|int, mixed>

getForm()

Getter for payment form that is using the processor.


    public
                    getForm() : CRM_Core_Form

Return values

CRM_Core_Form —

A form object

getID()

Getter for the id Payment Processor ID.


    public
                    getID() : int

Return values

int

getPaymentFormFields()

Get array of fields that should be displayed on the payment form.


    public
                    getPaymentFormFields() : array<string|int, mixed>

Common results are array('credit_card_type', 'credit_card_number', 'cvv2', 'credit_card_exp_date') or array('account_holder', 'bank_account_number', 'bank_identification_number', 'bank_name') or array()

Return values

array<string|int, mixed> —

Array of payment fields appropriate to the payment processor.

getPaymentFormFieldsMetadata()

Return an array of all the details about the fields potentially required for payment fields.


    public
                    getPaymentFormFieldsMetadata() : array<string|int, mixed>

Only those determined by getPaymentFormFields will actually be assigned to the form

Return values

array<string|int, mixed> —

field metadata

getPaymentInstrumentID()

Return the payment instrument ID to use.


    public
                    getPaymentInstrumentID() : int

Note: We normally SHOULD be returning the payment instrument of the payment processor. However there is an outstanding case where this needs overriding, which is when using CRM_Core_Payment_Manual which uses the pseudo-processor (id = 0).

i.e. If you're writing a Payment Processor you should NOT be using setPaymentInstrumentID() at all.

Return values

int

getPaymentProcessor()

Getter for the payment processor.


    public
                    getPaymentProcessor() : array<string|int, mixed>

The payment processor array is based on the civicrm_payment_processor table entry.

Return values

array<string|int, mixed> —

Payment processor array.

getPaymentTypeLabel()

Get label for the payment information type.


    public
                    getPaymentTypeLabel() : string

Return values

string

getPaymentTypeName()

Get name for the payment information type.


    public
                    getPaymentTypeName() : string

Return values

string

getPreApprovalDetails()

Get any details that may be available to the payment processor due to an approval process having happened.


    public
                    getPreApprovalDetails(array<string|int, mixed> $storedDetails) : array<string|int, mixed>

In some cases the browser is redirected to enter details on a processor site. Some details may be available as a result.

Parameters

$storedDetails : array<string|int, mixed>

Return values

array<string|int, mixed>

getRecurringScheduleUpdateHelpText()

Get the help text to present on the recurring update page.


    public
                    getRecurringScheduleUpdateHelpText() : string

This should reflect what can or cannot be edited.

Return values

string

getText()

Get help text information (help, description, etc.) about this payment, to display to the user.


    public
                    getText(string $context, array<string|int, mixed> $params) : string

Parameters

$context : string

Context of the text. Only explicitly supported contexts are handled without error. Currently supported:

contributionPageRecurringHelp (params: is_recur_installments, is_email_receipt)
contributionPageContinueText (params: amount, is_payment_to_existing)
cancelRecurDetailText: params: mode, amount, currency, frequency_interval, frequency_unit, installments, {membershipType|only if mode=auto_renew}, selfService (bool) - TRUE if user doesn't have "edit contributions" permission. ie. they are accessing via a "self-service" link from an email receipt or similar.
cancelRecurNotSupportedText

$params : array<string|int, mixed>

Parameters for the field, context specific.

Return values

string

getTitle()

Get the title of the payment processor to display to the user


    public
                    getTitle() : string

Return values

string

getVar()

Getter for accessing member vars.


    public
                    getVar(string $name) : null

Parameters

$name : string

Return values

null

handleIPN()

Handle incoming payment notification.


    public
            static        handleIPN() : mixed

IPNs, also called silent posts are notifications of payment outcomes or activity on an external site.

handlePaymentMethod()

Payment callback handler.


    public
            static        handlePaymentMethod(string $method[, array<string|int, mixed> $params = [] ]) : mixed

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

Parameters

$method : string: 'PaymentNotification' or 'PaymentCron'
$params : array<string|int, mixed> = []

isBackOffice()


    public
                    isBackOffice() : bool

Return values

bool

isSendReceiptForPending()

Should a receipt be sent out for a pending payment.


    public
                    isSendReceiptForPending() : mixed

e.g for traditional pay later & ones with a delayed settlement a pending receipt makes sense.

isSupported()

Check whether a method is present ( & supported ) by the payment processor object.


    public
                    isSupported(string $method) : bool

use $paymentProcessor->supports(array('cancelRecurring');

Parameters

$method : string: Method to check for.

Return values

bool

isSuppressSubmitButtons()

Some processors replace the form submit button with their own.


    public
                    isSuppressSubmitButtons() : mixed

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.

logPaymentNotification()

Log payment notification message to forensic system log.


    public
            static        logPaymentNotification(array<string|int, mixed> $params) : mixed

Parameters

$params : array<string|int, mixed>

paypalRedirect()

Redirect for paypal.


    public
            static        paypalRedirect(mixed &$paymentProcessor) : bool

Parameters

$paymentProcessor : mixed

Return values

bool

setBackOffice()

Set back office property.


    public
                    setBackOffice(bool $isBackOffice) : mixed

Parameters

$isBackOffice : bool

setBaseReturnUrl()

Set base return path (offsite processors).


    public
                    setBaseReturnUrl(string $url) : mixed

This is only useful with an internal civicrm form.

Parameters

$url : string: Internal civicrm path.

setBillingProfile()

Set the configured payment profile.


    public
                    setBillingProfile(int|string $value) : mixed

Parameters

$value : int|string

setCancelUrl()

Set cancel return URL (offsite processors).


    public
                    setCancelUrl(string $url) : mixed

This overrides $baseReturnUrl

Parameters

$url : string: Full url of site to return browser to upon failure.

setForm()

Setter for the payment form that wants to use the processor.


    public
                    setForm(CRM_Core_Form &$paymentForm) : mixed

Parameters

$paymentForm : CRM_Core_Form

setPaymentInstrumentID()


    public
                    setPaymentInstrumentID(int $paymentInstrumentID) : mixed

Set payment Instrument id - see note on getPaymentInstrumentID.

By default we actually ignore the form value. The manual processor takes it more seriously.

Parameters

$paymentInstrumentID : int

setPaymentProcessor()

Setter for the payment processor.


    public
                    setPaymentProcessor(array<string|int, mixed> $processor) : mixed

Parameters

$processor : array<string|int, mixed>

setSuccessUrl()

Set success return URL (offsite processors).


    public
                    setSuccessUrl(string $url) : mixed

This overrides $baseReturnUrl

Parameters

$url : string: Full url of site to return browser to upon success.

subscriptionURL()

Get url for users to manage this recurring contribution for this processor.


    public
                    subscriptionURL([int|null $entityID = NULL ][, string|null $entity = NULL ][, string $action = 'cancel' ]) : string|null

Parameters

$entityID : int|null = NULL
$entity : string|null = NULL
$action : string = 'cancel'

Return values

string|null

supports()

Check if capability is supported.


    public
                    supports(string $capability) : bool

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.

Parameters

$capability : string: E.g BackOffice, LiveMode, FutureRecurStartDate.

Return values

bool

supportsEditRecurringContribution()

Checks if back-office recurring edit is allowed


    public
                    supportsEditRecurringContribution() : bool

Return values

bool

supportsNoReturn()

Checks if payment processor supports not returning to the form processing.


    public
                    supportsNoReturn() : bool

The exists to support historical event form logic where emails are sent & the form postProcess hook is called before redirecting the browser where the user is redirected.

Return values

bool

supportsNoReturnForRecurring()

Checks if payment processor supports not returning to the form processing on recurring.


    public
                    supportsNoReturnForRecurring() : bool

The exists to support historical event form logic where emails are sent & the form postProcess hook is called before redirecting the browser where the user is redirected.

Return values

bool

supportsRecurring()

Checks if payment processor supports recurring contributions


    public
                    supportsRecurring() : bool

Return values

bool

supportsRefund()

Does this payment processor support refund?


    public
                    supportsRefund() : bool

Return values

bool

validatePaymentInstrument()

Default payment instrument validation.


    public
                    validatePaymentInstrument(array<string|int, mixed> $values, array<string|int, mixed> &$errors) : mixed

Payment processors should override this.

Parameters

$values : array<string|int, mixed>
$errors : array<string|int, mixed>

checkDupe()

Checks to see if invoice_id already exists in db.


    protected
                    checkDupe(int $invoiceId[, int|null $contributionID = NULL ]) : bool

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.

Parameters

$invoiceId : int: The ID to check.
$contributionID : int|null = NULL: If a contribution exists pass in the contribution ID.

Return values

bool —

True if invoice ID otherwise exists, else false

doDirectPayment()

Calling this from outside the payment subsystem is deprecated - use doPayment.


    protected
                    doDirectPayment(array<string|int, mixed> &$params) : array<string|int, mixed>

Does a server to server payment transaction.

Parameters

$params : array<string|int, mixed>: Assoc array of input parameters for this transaction.

Return values

array<string|int, mixed> —

the result in an nice formatted array (or an error object - but throwing exceptions is preferred)

doTransferCheckout()

Calling this from outside the payment subsystem is deprecated - use doPayment.


    protected
                    doTransferCheckout(array<string|int, mixed> &$params[, string $component = 'contribute' ]) : array<string|int, mixed>

Parameters

$params : array<string|int, mixed>: Assoc array of input parameters for this transaction.
$component : string = 'contribute'

Return values

array<string|int, mixed> —

the result in an nice formatted array (or an error object - but throwing exceptions is preferred)

getAllFields()

Get the metadata of all the fields configured for this processor.


    protected
                    getAllFields() : array<string|int, mixed>

Return values

array<string|int, mixed>

getAmount()

Get the submitted amount, padded to 2 decimal places, if needed.


    protected
                    getAmount([array<string|int, mixed> $params = [] ]) : string

Parameters

$params : array<string|int, mixed> = []

Return values

string

getBaseReturnUrl()

Get base url dependent on component.


    protected
                    getBaseReturnUrl() : string

(or preferably set it using the setter function).

Return values

string

getCreditCardFormFields()

Get array of fields that should be displayed on the payment form for credit cards.


    protected
                    getCreditCardFormFields() : array<string|int, mixed>

Return values

array<string|int, mixed>

getCurrency()

Get the currency for the transaction from the params.


    protected
                    getCurrency([mixed $params = [] ]) : string

Legacy wrapper. Better for a method to work on its own PropertyBag.

This code now uses PropertyBag to allow for old inputs like currencyID.

Parameters

$params : mixed = []

Return values

string

getDirectDebitFormFields()

Get array of fields that should be displayed on the payment form for direct debits.


    protected
                    getDirectDebitFormFields() : array<string|int, mixed>

Return values

array<string|int, mixed>

getGoBackUrl()

Get URl for when the back button is pressed.


    protected
                    getGoBackUrl(mixed $qfKey) : string

Parameters

$qfKey : mixed

Return values

string —

url

getMandatoryFields()

Get the metadata for all required fields.


    protected
                    getMandatoryFields() : mixed

getNotifyUrl()

Get the notify (aka ipn, web hook or silent post) url.


    protected
                    getNotifyUrl() : string

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.

Return values

string —

URL to notify outcome of transaction.

getPaymentDescription()

Get description of payment to pass to processor.


    protected
                    getPaymentDescription([array<string|int, mixed> $params = [] ][, int $length = 24 ]) : string

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

Parameters

$params : array<string|int, mixed> = []
$length : int = 24

Return values

string

getReturnFailUrl()

Get URL to return the browser to on failure.


    protected
                    getReturnFailUrl(string $key[, int $participantID = NULL ][, int $eventID = NULL ]) : string

Parameters

$key : string
$participantID : int = NULL
$eventID : int = NULL

Return values

string —

URL for a failing transactor to be redirected to.

getReturnSuccessUrl()

Get URL to return the browser to on success.


    protected
                    getReturnSuccessUrl(string $qfKey) : string

Parameters

$qfKey : string

Return values

string

setStatusPaymentCompleted()

Set the payment status to Completed


    protected
                    setStatusPaymentCompleted(PropertyBag|array<string|int, mixed> $params) : array<string|int, mixed>

Parameters

$params : PropertyBag|array<string|int, mixed>

Return values

array<string|int, mixed>

setStatusPaymentPending()

Set the payment status to Pending


    protected
                    setStatusPaymentPending(PropertyBag|array<string|int, mixed> $params) : array<string|int, mixed>

Parameters

$params : PropertyBag|array<string|int, mixed>

Return values

array<string|int, mixed>

supportsAccountLoginURL()

Checks if payment processor supports an account login URL TODO: This is checked by self::subscriptionURL but is only used if no entityID is found.


    protected
                    supportsAccountLoginURL() : bool

TODO: It is implemented by AuthorizeNET, any others?

Return values

bool

supportsBackOffice()

Are back office payments supported.


    protected
                    supportsBackOffice() : bool

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.

Return values

bool

supportsCancelRecurring()

Does this processor support cancelling recurring contributions through code.


    protected
                    supportsCancelRecurring() : bool

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.

Return values

bool

supportsCancelRecurringNotifyOptional()

Does the processor support the user having a choice as to whether to cancel the recurring with the processor?


    protected
                    supportsCancelRecurringNotifyOptional() : bool

If this returns TRUE then there will be an option to send a cancellation request in the cancellation form.

This would normally be false for processors where CiviCRM maintains the schedule.

Return values

bool

supportsChangeSubscriptionAmount()

Does this processor support changing the amount for recurring contributions through code.


    protected
                    supportsChangeSubscriptionAmount() : bool

If the processor returns true then it must be possible to update the amount from within CiviCRM that will be updated at the payment processor.

Return values

bool

supportsFutureRecurStartDate()

Should the first payment date be configurable when setting up back office recurring payments.


    protected
                    supportsFutureRecurStartDate() : bool

We set this to false for historical consistency but in fact most new processors use tokens for recurring and can support this

Return values

bool

supportsLiveMode()

Are live payments supported - e.g dummy doesn't support this.


    protected
                    supportsLiveMode() : bool

Return values

bool

supportsMultipleConcurrentPayments()

Can more than one transaction be processed at once?


    protected
                    supportsMultipleConcurrentPayments() : bool

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.

Return values

bool

supportsNoEmailProvided()

Does the processor work without an email address?


    protected
                    supportsNoEmailProvided() : bool

The historic assumption is that all processors require an email address. This capability allows a processor to state it does not need to be provided with an email address. NB: when this was added (Feb 2020), the Manual processor class overrides this but the only use of the capability is in the webform_civicrm module. It is not currently used in core but may be in future.

Return values

bool

supportsPreApproval()

Does this processor support pre-approval.


    protected
                    supportsPreApproval() : bool

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.

Return values

bool

supportsRecurContributionsForPledges()

Can recurring contributions be set against pledges.


    protected
                    supportsRecurContributionsForPledges() : bool

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.

Return values

bool

supportsTestMode()

Are test payments supported.


    protected
                    supportsTestMode() : bool

Return values

bool

supportsUpdateSubscriptionBillingInfo()

Does this processor support updating billing info for recurring contributions through code.


    protected
                    supportsUpdateSubscriptionBillingInfo() : bool

If the processor returns true then it must be possible to update billing info from within CiviCRM that will be updated at the payment processor.

Return values

bool

PaymentProcessorWithStandardBillingRequirements extends CRM_Core_Payment in package Application

Table of Contents

Constants

Properties

Methods

Constants

BILLING_MODE_BUTTON

BILLING_MODE_FORM

BILLING_MODE_NOTIFY

PAYMENT_TYPE_CREDIT_CARD

Tags

PAYMENT_TYPE_DIRECT_DEBIT

Tags

RECURRING_PAYMENT_END

RECURRING_PAYMENT_START

Properties

$_processorName

$_component

$_paymentProcessor

$backOffice

$baseReturnUrl

$billingProfile

$cancelUrl

$paymentInstrumentID

$propertyBag

$successUrl

Methods

__construct()

buildForm()

Parameters

Return values

checkConfig()

Return values

doCancelRecurring()

Parameters

Tags

Return values

doPayment()

Parameters

Tags

Return values

doPreApproval()

Parameters

doQuery()

Parameters

Return values

doRefund()

Parameters

Return values

extractCustomPropertiesForDoPayment()

Parameters

Tags

getBillingAddressFields()

Parameters

Return values

getBillingAddressFieldsMetadata()

Parameters

Return values

getCancelUrl()

Parameters

Return values

getEditableRecurringScheduleFields()

Return values

getForm()

Return values

getID()

Return values

getPaymentFormFields()

Tags

Return values

getPaymentFormFieldsMetadata()

Return values

getPaymentInstrumentID()

Tags

Return values

getPaymentProcessor()

Return values

getPaymentTypeLabel()

Tags

Return values

PaymentProcessorWithStandardBillingRequirements extends CRM_Core_Payment
in package

Application