4 * Licensed to CiviCRM under the Academic Free License version 3.0.
6 * Written and contributed by Ideal Solution, LLC (http://www.idealso.com)
13 * @author Marshal Newrock <marshal@idealso.com>
16 use Civi\Payment\Exception\PaymentProcessorException
;
17 use Civi\Payment\PropertyBag
;
20 * Dummy payment processor
22 class CRM_Core_Payment_Dummy
extends CRM_Core_Payment
{
25 protected $_doDirectPaymentResult = [];
28 * This support variable is used to allow the capabilities supported by the Dummy processor to be set from unit tests
29 * so that we don't need to create a lot of new processors to test combinations of features.
30 * Initially these capabilities are set to TRUE, however they can be altered by calling the setSupports function directly from outside the class.
33 protected $supports = [
34 'MultipleConcurrentPayments' => TRUE,
35 'EditRecurringContribution' => TRUE,
36 'CancelRecurringNotifyOptional' => TRUE,
38 'NoEmailProvided' => TRUE,
39 'CancelRecurring' => TRUE,
40 'FutureRecurStartDate' => TRUE,
45 * Set result from do Direct Payment for test purposes.
47 * @param array $doDirectPaymentResult
48 * Result to be returned from test.
50 public function setDoDirectPaymentResult($doDirectPaymentResult) {
51 $this->_doDirectPaymentResult
= $doDirectPaymentResult;
52 if (empty($this->_doDirectPaymentResult
['trxn_id'])) {
53 $this->_doDirectPaymentResult
['trxn_id'] = [];
56 $this->_doDirectPaymentResult
['trxn_id'] = (array) $doDirectPaymentResult['trxn_id'];
64 * The mode of operation: live or test.
66 * @param array $paymentProcessor
68 public function __construct($mode, &$paymentProcessor) {
70 $this->_paymentProcessor
= $paymentProcessor;
74 * Does this payment processor support refund?
78 public function supportsRefund() {
79 return $this->supports
['Refund'];
83 * Should the first payment date be configurable when setting up back office recurring payments.
85 * We set this to false for historical consistency but in fact most new processors use tokens for recurring and can support this
89 public function supportsFutureRecurStartDate() {
90 return $this->supports
['FutureRecurStartDate'];
94 * Can more than one transaction be processed at once?
96 * In general processors that process payment by server to server communication support this while others do not.
98 * In future we are likely to hit an issue where this depends on whether a token already exists.
102 protected function supportsMultipleConcurrentPayments() {
103 return $this->supports
['MultipleConcurrentPayments'];
107 * Checks if back-office recurring edit is allowed
111 public function supportsEditRecurringContribution() {
112 return $this->supports
['EditRecurringContribution'];
116 * Are back office payments supported.
118 * e.g paypal standard won't permit you to enter a credit card associated
119 * with someone else's login.
120 * The intention is to support off-site (other than paypal) & direct debit but that is not all working yet so to
121 * reach a 'stable' point we disable.
125 protected function supportsBackOffice() {
126 return $this->supports
['BackOffice'];
130 * Does the processor work without an email address?
132 * The historic assumption is that all processors require an email address. This capability
133 * allows a processor to state it does not need to be provided with an email address.
134 * NB: when this was added (Feb 2020), the Manual processor class overrides this but
135 * the only use of the capability is in the webform_civicrm module. It is not currently
136 * used in core but may be in future.
140 protected function supportsNoEmailProvided() {
141 return $this->supports
['NoEmailProvided'];
145 * Does this processor support cancelling recurring contributions through code.
147 * If the processor returns true it must be possible to take action from within CiviCRM
148 * that will result in no further payments being processed. In the case of token processors (e.g
149 * IATS, eWay) updating the contribution_recur table is probably sufficient.
153 protected function supportsCancelRecurring() {
154 return $this->supports
['CancelRecurring'];
158 * Does the processor support the user having a choice as to whether to cancel the recurring with the processor?
160 * If this returns TRUE then there will be an option to send a cancellation request in the cancellation form.
162 * This would normally be false for processors where CiviCRM maintains the schedule.
166 protected function supportsCancelRecurringNotifyOptional() {
167 return $this->supports
['CancelRecurringNotifyOptional'];
171 * Set the return value of support functions. By default it is TRUE
174 public function setSupports(array $support) {
175 $this->supports
= array_merge($this->supports
, $support);
179 * @param array|PropertyBag $params
181 * @param string $component
184 * Result array (containing at least the key payment_status_id)
186 * @throws \Civi\Payment\Exception\PaymentProcessorException
188 public function doPayment(&$params, $component = 'contribute') {
189 $this->_component
= $component;
190 $statuses = CRM_Contribute_BAO_Contribution
::buildOptions('contribution_status_id', 'validate');
192 $propertyBag = PropertyBag
::cast($params);
194 // If we have a $0 amount, skip call to processor and set payment_status to Completed.
195 // Conceivably a processor might override this - perhaps for setting up a token - but we don't
196 // have an example of that at the mome.
197 if ($propertyBag->getAmount() == 0) {
198 $result['payment_status_id'] = array_search('Completed', $statuses);
199 $result['payment_status'] = 'Completed';
203 // Invoke hook_civicrm_paymentProcessor
204 // In Dummy's case, there is no translation of parameters into
205 // the back-end's canonical set of parameters. But if a processor
206 // does this, it needs to invoke this hook after it has done translation,
207 // but before it actually starts talking to its proprietary back-end.
208 if ($propertyBag->getIsRecur()) {
209 $throwAnENoticeIfNotSetAsTheseAreRequired = $propertyBag->getRecurFrequencyInterval() . $propertyBag->getRecurFrequencyUnit();
211 // no translation in Dummy processor
212 CRM_Utils_Hook
::alterPaymentProcessorParams($this, $params, $propertyBag);
213 // This means we can test failing transactions by setting a past year in expiry. A full expiry check would
215 if (!empty($params['credit_card_exp_date']['Y']) && CRM_Utils_Time
::date('Y') >
216 CRM_Core_Payment_Form
::getCreditCardExpirationYear($params)) {
217 throw new PaymentProcessorException(ts('Invalid expiry date'));
220 if (!empty($this->_doDirectPaymentResult
)) {
221 $result = $this->_doDirectPaymentResult
;
222 if (empty($result['payment_status_id'])) {
223 $result['payment_status_id'] = array_search('Pending', $statuses);
224 $result['payment_status'] = 'Pending';
226 if ($result['payment_status_id'] === 'failed') {
227 throw new PaymentProcessorException($result['message'] ??
'failed');
229 $result['trxn_id'] = array_shift($this->_doDirectPaymentResult
['trxn_id']);
233 $result['trxn_id'] = $this->getTrxnID();
235 // Add a fee_amount so we can make sure fees are handled properly in underlying classes.
236 $result['fee_amount'] = 1.50;
237 $result['description'] = $this->getPaymentDescription($params);
239 if (!isset($result['payment_status_id'])) {
240 if (!empty($propertyBag->getIsRecur())) {
241 // See comment block.
242 $result['payment_status_id'] = array_search('Pending', $statuses);
243 $result['payment_status'] = 'Pending';
246 $result['payment_status_id'] = array_search('Completed', $statuses);
247 $result['payment_status'] = 'Completed';
255 * Submit a refund payment
257 * @throws \Civi\Payment\Exception\PaymentProcessorException
259 * @param array $params
260 * Assoc array of input parameters for this transaction.
262 public function doRefund(&$params) {}
265 * This function checks to see if we have the right config values.
268 * the error message if any
270 public function checkConfig() {
275 * Get an array of the fields that can be edited on the recurring contribution.
277 * Some payment processors support editing the amount and other scheduling details of recurring payments, especially
278 * those which use tokens. Others are fixed. This function allows the processor to return an array of the fields that
279 * can be updated from the contribution recur edit screen.
281 * The fields are likely to be a subset of these
284 * - 'frequency_interval',
285 * - 'frequency_unit',
287 * - 'next_sched_contribution_date',
289 * - 'failure_retry_day',
291 * The form does not restrict which fields from the contribution_recur table can be added (although if the html_type
292 * metadata is not defined in the xml for the field it will cause an error.
294 * Open question - would it make sense to return membership_id in this - which is sometimes editable and is on that
295 * form (UpdateSubscription).
299 public function getEditableRecurringScheduleFields() {
300 return ['amount', 'next_sched_contribution_date'];
304 * Cancel a recurring subscription.
306 * Payment processor classes should override this rather than implementing cancelSubscription.
308 * A PaymentProcessorException should be thrown if the update of the contribution_recur
309 * record should not proceed (in many cases this function does nothing
310 * as the payment processor does not need to take any action & this should silently
311 * proceed. Note the form layer will only call this after calling
312 * $processor->supports('cancelRecurring');
314 * @param \Civi\Payment\PropertyBag $propertyBag
318 * @throws \Civi\Payment\Exception\PaymentProcessorException
320 public function doCancelRecurring(PropertyBag
$propertyBag) {
321 return ['message' => ts('Recurring contribution cancelled')];
325 * Get a value for the transaction ID.
327 * Value is made up of the max existing value + a random string.
329 * Note the random string is likely a historical workaround.
333 protected function getTrxnID() {
334 $string = $this->_mode
;
335 $trxn_id = CRM_Core_DAO
::singleValueQuery("SELECT MAX(trxn_id) FROM civicrm_contribution WHERE trxn_id LIKE '{$string}_%'");
336 $trxn_id = str_replace($string, '', $trxn_id);
337 $trxn_id = (int) $trxn_id +
1;
338 return $string . '_' . $trxn_id . '_' . uniqid();