class CRM_Core_Payment_eWAY extends CRM_Core_Payment

Class CRM_Core_Payment_eWAY.

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

CHARSET

Properties

protected string $_component Component - ie. event or contribute. from CRM_Core_Payment
protected $_paymentProcessor from CRM_Core_Payment
protected string $baseReturnUrl Base url of the calling form (offsite processors). from CRM_Core_Payment
protected string $successUrl Return url upon success (offsite processors). from CRM_Core_Payment
protected string $cancelUrl Return url upon failure (offsite processors). from CRM_Core_Payment
protected int|string $billingProfile The profile configured to show on the billing form. from CRM_Core_Payment
protected int $paymentInstrumentID Payment instrument ID. from CRM_Core_Payment
protected bool $backOffice Is this a back office transaction. from CRM_Core_Payment

Methods

bool
isBackOffice()

No description

setBackOffice(bool $isBackOffice)

Set back office property.

int
getPaymentInstrumentID()

Get payment instrument id.

setPaymentInstrumentID(int $paymentInstrumentID)

Set payment Instrument id.

setBaseReturnUrl(string $url)

Set base return path (offsite processors).

setSuccessUrl(string $url)

Set success return URL (offsite processors).

setCancelUrl(string $url)

Set cancel return URL (offsite processors).

setBillingProfile(int|string $value)

Set the configured payment profile.

bool
buildForm(CRM_Core_Form $form)

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

static mixed
logPaymentNotification(array $params)

Log payment notification message to forensic system log.

bool
supports(string $capability)

Check if capability is supported.

bool
supportsBackOffice()

Are back office payments supported.

bool
supportsMultipleConcurrentPayments()

Can more than one transaction be processed at once?

bool
supportsLiveMode()

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

bool
supportsTestMode()

Are test payments supported.

bool
supportsFutureRecurStartDate()

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

bool
supportsCancelRecurring()

Does this processor support cancelling recurring contributions through code.

bool
supportsPreApproval()

Does this processor support pre-approval.

bool
supportsRecurContributionsForPledges()

Can recurring contributions be set against pledges.

doPreApproval(array $params)

Function to action pre-approval if supported

array
getPreApprovalDetails(array $storedDetails)

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

validatePaymentInstrument(array $values, array $errors)

Default payment instrument validation.

array
getPaymentProcessor()

Getter for the payment processor.

setPaymentProcessor(array $processor)

Setter for the payment processor.

setForm(CRM_Core_Form $paymentForm) deprecated

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

getForm() deprecated

Getter for payment form that is using the processor.

string
getText(string $context, array $params)

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

null
getVar(string $name)

Getter for accessing member vars.

string
getPaymentTypeName()

Get name for the payment information type.

string
getPaymentTypeLabel()

Get label for the payment information type.

array
getPaymentFormFields()

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

array
getEditableRecurringScheduleFields()

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

string
getRecurringScheduleUpdateHelpText()

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

array;
getMandatoryFields()

Get the metadata for all required fields.

array
getAllFields()

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

array
getCreditCardFormFields()

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

array
getDirectDebitFormFields()

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

array
getPaymentFormFieldsMetadata()

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

array
getBillingAddressFields(int $billingLocationID = NULL)

Get billing fields required for this processor.

array
getBillingAddressFieldsMetadata(int $billingLocationID = NULL)

Get form metadata for billing address fields.

string
getBaseReturnUrl()

Get base url dependent on component.

string
getCancelUrl(string $qfKey, int $participantID)

Get url to return to after cancelled or failed transaction.

string
getReturnSuccessUrl($qfKey)

Get URL to return the browser to on success.

string
getReturnFailUrl(string $key, int $participantID = NULL, int $eventID = NULL)

Get URL to return the browser to on failure.

string
getGoBackUrl($qfKey)

Get URl for when the back button is pressed.

string
getNotifyUrl()

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

array
doDirectPayment(array $params)

Sends request and receive response from eWAY payment process.

array
doPayment(array $params, string $component = 'contribute')

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

array
doQuery(array $params)

Query payment processor for details about a transaction.

string
checkConfig()


This public function checks to see if we have the right processor config values set

static bool
paypalRedirect($paymentProcessor)

Redirect for paypal.

static 
handleIPN()

Handle incoming payment notification.

static 
handlePaymentMethod(string $method, array $params = array())

Payment callback handler.

bool
isSupported(string $method) deprecated

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

isSuppressSubmitButtons()

Some processors replace the form submit button with their own.

bool
checkDupe(int $invoiceId, null $contributionID = NULL)

Checks to see if invoice_id already exists in db.

string
subscriptionURL(int $entityID = NULL, null $entity = NULL, string $action = 'cancel')

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

string
getPaymentDescription(array $params, int $length = 24)

Get description of payment to pass to processor.

bool
supportsEditRecurringContribution()

Checks if backoffice recurring edit is allowed

isSendReceiptForPending()

Should a receipt be sent out for a pending payment.

__construct(string $mode, int $paymentProcessor)


Constructor

bool
isError(object $response)

Checks the eWAY response status - returning a boolean false if status != 'true'.

object
errorExit(int $errorCode = NULL, string $errorMessage = NULL)

Produces error message and returns from class.

Details

in CRM_Core_Payment at line 141
bool isBackOffice()

Return Value

bool

in CRM_Core_Payment at line 150
setBackOffice(bool $isBackOffice)

Set back office property.

Parameters

bool $isBackOffice

in CRM_Core_Payment at line 159
int getPaymentInstrumentID()

Get payment instrument id.

Return Value

int

in CRM_Core_Payment 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.

Parameters

int $paymentInstrumentID

in CRM_Core_Payment at line 182
setBaseReturnUrl(string $url)

Set base return path (offsite processors).

This is only useful with an internal civicrm form.

Parameters

string $url Internal civicrm path.

in CRM_Core_Payment at line 194
setSuccessUrl(string $url)

Set success return URL (offsite processors).

This overrides $baseReturnUrl

Parameters

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

in CRM_Core_Payment at line 206
setCancelUrl(string $url)

Set cancel return URL (offsite processors).

This overrides $baseReturnUrl

Parameters

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

in CRM_Core_Payment at line 215
setBillingProfile(int|string $value)

Set the configured payment profile.

Parameters

int|string $value

in CRM_Core_Payment at line 227
bool buildForm(CRM_Core_Form $form)

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

Parameters

CRM_Core_Form $form

Return Value

bool Should form building stop at this point?

in CRM_Core_Payment at line 240
static mixed logPaymentNotification(array $params)

Log payment notification message to forensic system log.

Parameters

array $params

Return Value

mixed

in CRM_Core_Payment 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.

Parameters

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

Return Value

bool

in CRM_Core_Payment 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.

Return Value

bool

in CRM_Core_Payment 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.

Return Value

bool

in CRM_Core_Payment at line 315
protected bool supportsLiveMode()

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

Return Value

bool

in CRM_Core_Payment at line 324
protected bool supportsTestMode()

Are test payments supported.

Return Value

bool

in CRM_Core_Payment 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

Return Value

bool

in CRM_Core_Payment 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.

Return Value

bool

in CRM_Core_Payment 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.

Return Value

bool

in CRM_Core_Payment 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.

Return Value

bool

in CRM_Core_Payment at line 393
doPreApproval(array $params)

Function to action pre-approval if supported

Parameters

array $params 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.

in CRM_Core_Payment 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.

Parameters

array $storedDetails

Return Value

array

in CRM_Core_Payment 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.

Parameters

array $values
array $errors

in CRM_Core_Payment at line 433
array getPaymentProcessor()

Getter for the payment processor.

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

Return Value

array Payment processor array.

in CRM_Core_Payment at line 442
setPaymentProcessor(array $processor)

Setter for the payment processor.

Parameters

array $processor

in CRM_Core_Payment at line 453
setForm(CRM_Core_Form $paymentForm) deprecated

deprecated

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

Parameters

CRM_Core_Form $paymentForm

in CRM_Core_Payment at line 463
CRM_Core_Form getForm() deprecated

deprecated

Getter for payment form that is using the processor.

Return Value

CRM_Core_Form A form object

in CRM_Core_Payment at line 482
string getText(string $context, array $params)

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

Parameters

string $context Context of the text. Only explicitly supported contexts are handled without error. Currently supported: - contributionPageRecurringHelp (params: is_recur_installments, is_email_receipt)
array $params Parameters for the field, context specific.

Return Value

string

in CRM_Core_Payment at line 512
null getVar(string $name)

Getter for accessing member vars.

Parameters

string $name

Return Value

null

in CRM_Core_Payment at line 521
string getPaymentTypeName()

Get name for the payment information type.

Return Value

string

in CRM_Core_Payment at line 530
string getPaymentTypeLabel()

Get label for the payment information type.

Return Value

string

in CRM_Core_Payment at line 540
array getPaymentFormFields()

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

Return Value

array

Exceptions

CiviCRM_API3_Exception

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

Return Value

array

in CRM_Core_Payment 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.

Return Value

string

in CRM_Core_Payment at line 597
protected array; getMandatoryFields()

Get the metadata for all required fields.

Return Value

array;

in CRM_Core_Payment at line 612
protected array getAllFields()

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

Return Value

array

in CRM_Core_Payment at line 622
protected array getCreditCardFormFields()

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

Return Value

array

in CRM_Core_Payment at line 636
protected array getDirectDebitFormFields()

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

Return Value

array

in CRM_Core_Payment 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

Return Value

array field metadata

in CRM_Core_Payment 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.

Parameters

int $billingLocationID

Return Value

array

in CRM_Core_Payment at line 848
array getBillingAddressFieldsMetadata(int $billingLocationID = NULL)

Get form metadata for billing address fields.

Parameters

int $billingLocationID

Return Value

array Array of metadata for address fields.

in CRM_Core_Payment at line 962
protected string getBaseReturnUrl()

Get base url dependent on component.

(or preferably set it using the setter function).

Return Value

string

in CRM_Core_Payment at line 983
string getCancelUrl(string $qfKey, int $participantID)

Get url to return to after cancelled or failed transaction.

Parameters

string $qfKey
int $participantID

Return Value

string cancel url

in CRM_Core_Payment at line 1014
protected string getReturnSuccessUrl($qfKey)

Get URL to return the browser to on success.

Parameters

$qfKey

Return Value

string

in CRM_Core_Payment at line 1037
protected string getReturnFailUrl(string $key, int $participantID = NULL, int $eventID = NULL)

Get URL to return the browser to on failure.

Parameters

string $key
int $participantID
int $eventID

Return Value

string URL for a failing transactor to be redirected to.

in CRM_Core_Payment at line 1064
protected string getGoBackUrl($qfKey)

Get URl for when the back button is pressed.

Parameters

$qfKey

Return Value

string url

in CRM_Core_Payment 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.

Return Value

string URL to notify outcome of transaction.

at line 140
array doDirectPayment(array $params)

Sends request and receive response from eWAY payment process.

Parameters

array $params Assoc array of input parameters for this transaction.

Return Value

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

Exceptions

Exception

in CRM_Core_Payment 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

Parameters

array $params
string $component

Return Value

array Result array

Exceptions

PaymentProcessorException

in CRM_Core_Payment at line 1183
array doQuery(array $params)

Query payment processor for details about a transaction.

Parameters

array $params 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 Value

array 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

at line 467
string checkConfig()


This public function checks to see if we have the right processor config values set

NOTE: Called by Events and Contribute to check config params are set prior to trying register any credit card details

Return Value

string the error message if any

in CRM_Core_Payment at line 1204
static bool paypalRedirect($paymentProcessor)

Redirect for paypal.

Parameters

$paymentProcessor

Return Value

bool

in CRM_Core_Payment 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.

in CRM_Core_Payment 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

Parameters

string $method 'PaymentNotification' or 'PaymentCron'
array $params

Exceptions

CRM_Core_Exception
Exception

in CRM_Core_Payment at line 1353
bool isSupported(string $method) deprecated

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

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

Parameters

string $method Method to check for.

Return Value

bool

in CRM_Core_Payment 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.

in CRM_Core_Payment 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.

Parameters

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

Return Value

bool True if invoice ID otherwise exists, else false

in CRM_Core_Payment 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.

Parameters

int $entityID
null $entity
string $action

Return Value

string

in CRM_Core_Payment 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

Parameters

array $params
int $length

Return Value

string

in CRM_Core_Payment at line 1503
bool supportsEditRecurringContribution()

Checks if backoffice recurring edit is allowed

Return Value

bool

in CRM_Core_Payment 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.

at line 124
__construct(string $mode, int $paymentProcessor)


Constructor

Parameters

string $mode The mode of operation: live or test.
int $paymentProcessor

at line 422
bool isError(object $response)

Checks the eWAY response status - returning a boolean false if status != 'true'.

Parameters

object $response

Return Value

bool

at line 439
object errorExit(int $errorCode = NULL, string $errorMessage = NULL)

Produces error message and returns from class.

Parameters

int $errorCode
string $errorMessage

Return Value

object