Merge pull request #5561 from agh1/extension-perm-desc
[civicrm-core.git] / CRM / Core / Payment.php
1 <?php
2 /*
3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.6 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2015 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
9 | |
10 | CiviCRM is free software; you can copy, modify, and distribute it |
11 | under the terms of the GNU Affero General Public License |
12 | Version 3, 19 November 2007 and the CiviCRM Licensing Exception. |
13 | |
14 | CiviCRM is distributed in the hope that it will be useful, but |
15 | WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
17 | See the GNU Affero General Public License for more details. |
18 | |
19 | You should have received a copy of the GNU Affero General Public |
20 | License and the CiviCRM Licensing Exception along |
21 | with this program; if not, contact CiviCRM LLC |
22 | at info[AT]civicrm[DOT]org. If you have questions about the |
23 | GNU Affero General Public License or the licensing of CiviCRM, |
24 | see the CiviCRM license FAQ at http://civicrm.org/licensing |
25 +--------------------------------------------------------------------+
26 */
27
28 use Civi\Payment\System;
29
30 /**
31 * Class CRM_Core_Payment.
32 *
33 * This class is the main class for the payment processor subsystem.
34 *
35 * It is the parent class for payment processors. It also holds some IPN related functions
36 * that need to be moved. In particular handlePaymentMethod should be moved to a factory class.
37 */
38 abstract class CRM_Core_Payment {
39
40 /**
41 * How are we getting billing information?
42 *
43 * FORM - we collect it on the same page
44 * BUTTON - the processor collects it and sends it back to us via some protocol
45 */
46 const
47 BILLING_MODE_FORM = 1,
48 BILLING_MODE_BUTTON = 2,
49 BILLING_MODE_NOTIFY = 4;
50
51 /**
52 * Which payment type(s) are we using?
53 *
54 * credit card
55 * direct debit
56 * or both
57 * @todo create option group - nb omnipay uses a 3rd type - transparent redirect cc
58 */
59 const
60 PAYMENT_TYPE_CREDIT_CARD = 1,
61 PAYMENT_TYPE_DIRECT_DEBIT = 2;
62
63 /**
64 * Subscription / Recurring payment Status
65 * START, END
66 */
67 const
68 RECURRING_PAYMENT_START = 'START',
69 RECURRING_PAYMENT_END = 'END';
70
71 protected $_paymentProcessor;
72
73 /**
74 * Singleton function used to manage this object.
75 *
76 * We will migrate to calling Civi\Payment\System::singleton()->getByProcessor($paymentProcessor)
77 * & Civi\Payment\System::singleton()->getById($paymentProcessor) directly as the main access methods & work
78 * to remove this function all together
79 *
80 * @param string $mode
81 * The mode of operation: live or test.
82 * @param array $paymentProcessor
83 * The details of the payment processor being invoked.
84 * @param object $paymentForm
85 * Deprecated - avoid referring to this if possible. If you have to use it document why as this is scary interaction.
86 * @param bool $force
87 * Should we force a reload of this payment object.
88 *
89 * @return CRM_Core_Payment
90 * @throws \CRM_Core_Exception
91 */
92 public static function &singleton($mode = 'test', &$paymentProcessor, &$paymentForm = NULL, $force = FALSE) {
93 // make sure paymentProcessor is not empty
94 // CRM-7424
95 if (empty($paymentProcessor)) {
96 return CRM_Core_DAO::$_nullObject;
97 }
98 //we use two lines because we can't remove the '&singleton' without risking breakage
99 //of extension classes that extend this one
100 $object = Civi\Payment\System::singleton()->getByProcessor($paymentProcessor);
101 return $object;
102 }
103
104 /**
105 * Log payment notification message to forensic system log.
106 *
107 * @todo move to factory class \Civi\Payment\System (or similar)
108 *
109 * @param array $params
110 *
111 * @return mixed
112 */
113 public static function logPaymentNotification($params) {
114 $message = 'payment_notification ';
115 if (!empty($params['processor_name'])) {
116 $message .= 'processor_name=' . $params['processor_name'];
117 }
118 if (!empty($params['processor_id'])) {
119 $message .= 'processor_id=' . $params['processor_id'];
120 }
121
122 $log = new CRM_Utils_SystemLogger();
123 $log->alert($message, $_REQUEST);
124 }
125
126 /**
127 * Check if capability is supported.
128 *
129 * Capabilities have a one to one relationship with capability-related functions on this class.
130 *
131 * Payment processor classes should over-ride the capability-specific function rather than this one.
132 *
133 * @param string $capability
134 * E.g BackOffice, LiveMode, FutureRecurStartDate.
135 *
136 * @return bool
137 */
138 public function supports($capability) {
139 $function = 'supports' . ucfirst($capability);
140 if (method_exists($this, $function)) {
141 return $this->$function();
142 }
143 return FALSE;
144 }
145
146 /**
147 * Are back office payments supported.
148 *
149 * e.g paypal standard won't permit you to enter a credit card associated
150 * with someone else's login.
151 * The intention is to support off-site (other than paypal) & direct debit but that is not all working yet so to
152 * reach a 'stable' point we disable.
153 *
154 * @return bool
155 */
156 protected function supportsBackOffice() {
157 if ($this->_paymentProcessor['billing_mode'] == 4 || $this->_paymentProcessor['payment_type'] != 1) {
158 return FALSE;
159 }
160 else {
161 return TRUE;
162 }
163 }
164
165 /**
166 * Are live payments supported - e.g dummy doesn't support this.
167 *
168 * @return bool
169 */
170 protected function supportsLiveMode() {
171 return TRUE;
172 }
173
174 /**
175 * Are test payments supported.
176 *
177 * @return bool
178 */
179 protected function supportsTestMode() {
180 return TRUE;
181 }
182
183 /**
184 * Should the first payment date be configurable when setting up back office recurring payments.
185 *
186 * We set this to false for historical consistency but in fact most new processors use tokens for recurring and can support this
187 *
188 * @return bool
189 */
190 protected function supportsFutureRecurStartDate() {
191 return FALSE;
192 }
193
194 /**
195 * Default payment instrument validation.
196 *
197 * Implement the usual Luhn algorithm via a static function in the CRM_Core_Payment_Form if it's a credit card
198 * Not a static function, because I need to check for payment_type.
199 *
200 * @param array $values
201 * @param array $errors
202 */
203 public function validatePaymentInstrument($values, &$errors) {
204 if ($this->_paymentProcessor['payment_type'] == 1) {
205 CRM_Core_Payment_Form::validateCreditCard($values, $errors);
206 }
207 }
208
209 /**
210 * Getter for the payment processor.
211 *
212 * The payment processor array is based on the civicrm_payment_processor table entry.
213 *
214 * @return array
215 * Payment processor array.
216 */
217 public function getPaymentProcessor() {
218 return $this->_paymentProcessor;
219 }
220
221 /**
222 * Setter for the payment processor.
223 *
224 * @param array $processor
225 */
226 public function setPaymentProcessor($processor) {
227 $this->_paymentProcessor = $processor;
228 }
229
230 /**
231 * Setter for the payment form that wants to use the processor.
232 *
233 * @deprecated
234 *
235 * @param CRM_Core_Form $paymentForm
236 */
237 public function setForm(&$paymentForm) {
238 $this->_paymentForm = $paymentForm;
239 }
240
241 /**
242 * Getter for payment form that is using the processor.
243 * @deprecated
244 * @return CRM_Core_Form
245 * A form object
246 */
247 public function getForm() {
248 return $this->_paymentForm;
249 }
250
251 /**
252 * Getter for accessing member vars.
253 *
254 * @todo believe this is unused
255 *
256 * @param string $name
257 *
258 * @return null
259 */
260 public function getVar($name) {
261 return isset($this->$name) ? $this->$name : NULL;
262 }
263
264 /**
265 * Get name for the payment information type.
266 * @todo - use option group + name field (like Omnipay does)
267 * @return string
268 */
269 public function getPaymentTypeName() {
270 return $this->_paymentProcessor['payment_type'] == 1 ? 'credit_card' : 'direct_debit';
271 }
272
273 /**
274 * Get label for the payment information type.
275 * @todo - use option group + labels (like Omnipay does)
276 * @return string
277 */
278 public function getPaymentTypeLabel() {
279 return $this->_paymentProcessor['payment_type'] == 1 ? 'Credit Card' : 'Direct Debit';
280 }
281
282 /**
283 * Get array of fields that should be displayed on the payment form.
284 * @todo make payment type an option value & use it in the function name - currently on debit & credit card work
285 * @return array
286 * @throws CiviCRM_API3_Exception
287 */
288 public function getPaymentFormFields() {
289 if ($this->_paymentProcessor['billing_mode'] == 4) {
290 return array();
291 }
292 return $this->_paymentProcessor['payment_type'] == 1 ? $this->getCreditCardFormFields() : $this->getDirectDebitFormFields();
293 }
294
295 /**
296 * Get array of fields that should be displayed on the payment form for credit cards.
297 *
298 * @return array
299 */
300 protected function getCreditCardFormFields() {
301 return array(
302 'credit_card_type',
303 'credit_card_number',
304 'cvv2',
305 'credit_card_exp_date',
306 );
307 }
308
309 /**
310 * Get array of fields that should be displayed on the payment form for direct debits.
311 *
312 * @return array
313 */
314 protected function getDirectDebitFormFields() {
315 return array(
316 'account_holder',
317 'bank_account_number',
318 'bank_identification_number',
319 'bank_name',
320 );
321 }
322
323 /**
324 * Return an array of all the details about the fields potentially required for payment fields.
325 *
326 * Only those determined by getPaymentFormFields will actually be assigned to the form
327 *
328 * @return array
329 * field metadata
330 */
331 public function getPaymentFormFieldsMetadata() {
332 //@todo convert credit card type into an option value
333 $creditCardType = array('' => ts('- select -')) + CRM_Contribute_PseudoConstant::creditCard();
334 return array(
335 'credit_card_number' => array(
336 'htmlType' => 'text',
337 'name' => 'credit_card_number',
338 'title' => ts('Card Number'),
339 'cc_field' => TRUE,
340 'attributes' => array(
341 'size' => 20,
342 'maxlength' => 20,
343 'autocomplete' => 'off',
344 'class' => 'creditcard',
345 ),
346 'is_required' => TRUE,
347 ),
348 'cvv2' => array(
349 'htmlType' => 'text',
350 'name' => 'cvv2',
351 'title' => ts('Security Code'),
352 'cc_field' => TRUE,
353 'attributes' => array(
354 'size' => 5,
355 'maxlength' => 10,
356 'autocomplete' => 'off',
357 ),
358 'is_required' => CRM_Core_BAO_Setting::getItem(CRM_Core_BAO_Setting::CONTRIBUTE_PREFERENCES_NAME,
359 'cvv_backoffice_required',
360 NULL,
361 1
362 ),
363 'rules' => array(
364 array(
365 'rule_message' => ts('Please enter a valid value for your card security code. This is usually the last 3-4 digits on the card\'s signature panel.'),
366 'rule_name' => 'integer',
367 'rule_parameters' => NULL,
368 ),
369 ),
370 ),
371 'credit_card_exp_date' => array(
372 'htmlType' => 'date',
373 'name' => 'credit_card_exp_date',
374 'title' => ts('Expiration Date'),
375 'cc_field' => TRUE,
376 'attributes' => CRM_Core_SelectValues::date('creditCard'),
377 'is_required' => TRUE,
378 'rules' => array(
379 array(
380 'rule_message' => ts('Card expiration date cannot be a past date.'),
381 'rule_name' => 'currentDate',
382 'rule_parameters' => TRUE,
383 ),
384 ),
385 ),
386 'credit_card_type' => array(
387 'htmlType' => 'select',
388 'name' => 'credit_card_type',
389 'title' => ts('Card Type'),
390 'cc_field' => TRUE,
391 'attributes' => $creditCardType,
392 'is_required' => FALSE,
393 ),
394 'account_holder' => array(
395 'htmlType' => 'text',
396 'name' => 'account_holder',
397 'title' => ts('Account Holder'),
398 'cc_field' => TRUE,
399 'attributes' => array(
400 'size' => 20,
401 'maxlength' => 34,
402 'autocomplete' => 'on',
403 ),
404 'is_required' => TRUE,
405 ),
406 //e.g. IBAN can have maxlength of 34 digits
407 'bank_account_number' => array(
408 'htmlType' => 'text',
409 'name' => 'bank_account_number',
410 'title' => ts('Bank Account Number'),
411 'cc_field' => TRUE,
412 'attributes' => array(
413 'size' => 20,
414 'maxlength' => 34,
415 'autocomplete' => 'off',
416 ),
417 'rules' => array(
418 array(
419 'rule_message' => ts('Please enter a valid Bank Identification Number (value must not contain punctuation characters).'),
420 'rule_name' => 'nopunctuation',
421 'rule_parameters' => NULL,
422 ),
423 ),
424 'is_required' => TRUE,
425 ),
426 //e.g. SWIFT-BIC can have maxlength of 11 digits
427 'bank_identification_number' => array(
428 'htmlType' => 'text',
429 'name' => 'bank_identification_number',
430 'title' => ts('Bank Identification Number'),
431 'cc_field' => TRUE,
432 'attributes' => array(
433 'size' => 20,
434 'maxlength' => 11,
435 'autocomplete' => 'off',
436 ),
437 'is_required' => TRUE,
438 'rules' => array(
439 array(
440 'rule_message' => ts('Please enter a valid Bank Identification Number (value must not contain punctuation characters).'),
441 'rule_name' => 'nopunctuation',
442 'rule_parameters' => NULL,
443 ),
444 ),
445 ),
446 'bank_name' => array(
447 'htmlType' => 'text',
448 'name' => 'bank_name',
449 'title' => ts('Bank Name'),
450 'cc_field' => TRUE,
451 'attributes' => array(
452 'size' => 20,
453 'maxlength' => 64,
454 'autocomplete' => 'off',
455 ),
456 'is_required' => TRUE,
457
458 ),
459 );
460 }
461
462 /**
463 * Calling this from outside the payment subsystem is deprecated - use doPayment.
464 *
465 * Does a server to server payment transaction.
466 *
467 * Note that doPayment will throw an exception so the code may need to be modified
468 *
469 * @param array $params
470 * Assoc array of input parameters for this transaction.
471 *
472 * @return array
473 * the result in an nice formatted array (or an error object)
474 * @abstract
475 */
476 abstract protected function doDirectPayment(&$params);
477
478 /**
479 * Process payment - this function wraps around both doTransferPayment and doDirectPayment.
480 *
481 * The function ensures an exception is thrown & moves some of this logic out of the form layer and makes the forms
482 * more agnostic.
483 *
484 * @param array $params
485 *
486 * @param $component
487 *
488 * @return array
489 * (modified)
490 * @throws CRM_Core_Exception
491 */
492 public function doPayment(&$params, $component = 'contribute') {
493 if ($this->_paymentProcessor['billing_mode'] == 4) {
494 $result = $this->doTransferCheckout($params, $component);
495 }
496 else {
497 $result = $this->doDirectPayment($params, $component);
498 }
499 if (is_a($result, 'CRM_Core_Error')) {
500 throw new CRM_Core_Exception(CRM_Core_Error::getMessages($result));
501 }
502 //CRM-15767 - Submit Credit Card Contribution not being saved
503 return $result;
504 }
505
506 /**
507 * This function checks to see if we have the right config values.
508 *
509 * @return string
510 * the error message if any
511 */
512 abstract protected function checkConfig();
513
514 /**
515 * Redirect for paypal.
516 *
517 * @todo move to paypal class or remove
518 *
519 * @param $paymentProcessor
520 *
521 * @return bool
522 */
523 public static function paypalRedirect(&$paymentProcessor) {
524 if (!$paymentProcessor) {
525 return FALSE;
526 }
527
528 if (isset($_GET['payment_date']) &&
529 isset($_GET['merchant_return_link']) &&
530 CRM_Utils_Array::value('payment_status', $_GET) == 'Completed' &&
531 $paymentProcessor['payment_processor_type'] == "PayPal_Standard"
532 ) {
533 return TRUE;
534 }
535
536 return FALSE;
537 }
538
539 /**
540 * Handle incoming payment notification.
541 *
542 * IPNs, also called silent posts are notifications of payment outcomes or activity on an external site.
543 *
544 * @todo move to0 \Civi\Payment\System factory method
545 * Page callback for civicrm/payment/ipn
546 */
547 public static function handleIPN() {
548 self::handlePaymentMethod(
549 'PaymentNotification',
550 array(
551 'processor_name' => @$_GET['processor_name'],
552 'processor_id' => @$_GET['processor_id'],
553 'mode' => @$_GET['mode'],
554 )
555 );
556 CRM_Utils_System::civiExit();
557 }
558
559 /**
560 * Payment callback handler.
561 *
562 * The processor_name or processor_id is passed in.
563 * Note that processor_id is more reliable as one site may have more than one instance of a
564 * processor & ideally the processor will be validating the results
565 * Load requested payment processor and call that processor's handle<$method> method
566 *
567 * @todo move to \Civi\Payment\System factory method
568 *
569 * @param string $method
570 * 'PaymentNotification' or 'PaymentCron'
571 * @param array $params
572 */
573 public static function handlePaymentMethod($method, $params = array()) {
574 if (!isset($params['processor_id']) && !isset($params['processor_name'])) {
575 CRM_Core_Error::fatal("Either 'processor_id' or 'processor_name' param is required for payment callback");
576 }
577 self::logPaymentNotification($params);
578
579 $sql = "SELECT ppt.class_name, ppt.name as processor_name, pp.id AS processor_id
580 FROM civicrm_payment_processor_type ppt
581 INNER JOIN civicrm_payment_processor pp
582 ON pp.payment_processor_type_id = ppt.id
583 AND pp.is_active";
584
585 if (isset($params['processor_id'])) {
586 $sql .= " WHERE pp.id = %2";
587 $args[2] = array($params['processor_id'], 'Integer');
588 $notFound = "No active instances of payment processor ID#'{$params['processor_id']}' were found.";
589 }
590 else {
591 // This is called when processor_name is passed - passing processor_id instead is recommended.
592 $sql .= " WHERE ppt.name = %2 AND pp.is_test = %1";
593 $args[1] = array(
594 (CRM_Utils_Array::value('mode', $params) == 'test') ? 1 : 0,
595 'Integer',
596 );
597 $args[2] = array($params['processor_name'], 'String');
598 $notFound = "No active instances of the '{$params['processor_name']}' payment processor were found.";
599 }
600
601 $dao = CRM_Core_DAO::executeQuery($sql, $args);
602
603 // Check whether we found anything at all.
604 if (!$dao->N) {
605 CRM_Core_Error::fatal($notFound);
606 }
607
608 $method = 'handle' . $method;
609 $extension_instance_found = FALSE;
610
611 // In all likelihood, we'll just end up with the one instance returned here. But it's
612 // possible we may get more. Hence, iterate through all instances ..
613
614 while ($dao->fetch()) {
615 // Check pp is extension
616 $ext = CRM_Extension_System::singleton()->getMapper();
617 if ($ext->isExtensionKey($dao->class_name)) {
618 $paymentClass = $ext->keyToClass($dao->class_name, 'payment');
619 require_once $ext->classToPath($paymentClass);
620 }
621 else {
622 // Legacy or extension as module instance
623 if (empty($paymentClass)) {
624 $paymentClass = 'CRM_Core_' . $dao->class_name;
625
626 }
627 }
628
629 $processorInstance = Civi\Payment\System::singleton()->getById($dao->processor_id);
630
631 // Should never be empty - we already established this processor_id exists and is active.
632 if (empty($processorInstance)) {
633 continue;
634 }
635
636 // Does PP implement this method, and can we call it?
637 if (!method_exists($processorInstance, $method) ||
638 !is_callable(array($processorInstance, $method))
639 ) {
640 // on the off chance there is a double implementation of this processor we should keep looking for another
641 // note that passing processor_id is more reliable & we should work to deprecate processor_name
642 continue;
643 }
644
645 // Everything, it seems, is ok - execute pp callback handler
646 $processorInstance->$method();
647 $extension_instance_found = TRUE;
648 }
649
650 if (!$extension_instance_found) {
651 CRM_Core_Error::fatal(
652 "No extension instances of the '{$params['processor_name']}' payment processor were found.<br />" .
653 "$method method is unsupported in legacy payment processors."
654 );
655 }
656 }
657
658 /**
659 * Check whether a method is present ( & supported ) by the payment processor object.
660 *
661 * @param string $method
662 * Method to check for.
663 *
664 * @return bool
665 */
666 public function isSupported($method = 'cancelSubscription') {
667 return method_exists(CRM_Utils_System::getClassName($this), $method);
668 }
669
670 /**
671 * Get url for users to manage this recurring contribution for this processor.
672 *
673 * @param int $entityID
674 * @param null $entity
675 * @param string $action
676 *
677 * @return string
678 */
679 public function subscriptionURL($entityID = NULL, $entity = NULL, $action = 'cancel') {
680 // Set URL
681 switch ($action) {
682 case 'cancel':
683 $url = 'civicrm/contribute/unsubscribe';
684 break;
685
686 case 'billing':
687 //in notify mode don't return the update billing url
688 if (!$this->isSupported('updateSubscriptionBillingInfo')) {
689 return NULL;
690 }
691 $url = 'civicrm/contribute/updatebilling';
692 break;
693
694 case 'update':
695 $url = 'civicrm/contribute/updaterecur';
696 break;
697 }
698
699 $session = CRM_Core_Session::singleton();
700 $userId = $session->get('userID');
701 $contactID = 0;
702 $checksumValue = '';
703 $entityArg = '';
704
705 // Find related Contact
706 if ($entityID) {
707 switch ($entity) {
708 case 'membership':
709 $contactID = CRM_Core_DAO::getFieldValue("CRM_Member_DAO_Membership", $entityID, "contact_id");
710 $entityArg = 'mid';
711 break;
712
713 case 'contribution':
714 $contactID = CRM_Core_DAO::getFieldValue("CRM_Contribute_DAO_Contribution", $entityID, "contact_id");
715 $entityArg = 'coid';
716 break;
717
718 case 'recur':
719 $sql = "
720 SELECT con.contact_id
721 FROM civicrm_contribution_recur rec
722 INNER JOIN civicrm_contribution con ON ( con.contribution_recur_id = rec.id )
723 WHERE rec.id = %1
724 GROUP BY rec.id";
725 $contactID = CRM_Core_DAO::singleValueQuery($sql, array(1 => array($entityID, 'Integer')));
726 $entityArg = 'crid';
727 break;
728 }
729 }
730
731 // Add entity arguments
732 if ($entityArg != '') {
733 // Add checksum argument
734 if ($contactID != 0 && $userId != $contactID) {
735 $checksumValue = '&cs=' . CRM_Contact_BAO_Contact_Utils::generateChecksum($contactID, NULL, 'inf');
736 }
737 return CRM_Utils_System::url($url, "reset=1&{$entityArg}={$entityID}{$checksumValue}", TRUE, NULL, FALSE, TRUE);
738 }
739
740 // Else login URL
741 if ($this->isSupported('accountLoginURL')) {
742 return $this->accountLoginURL();
743 }
744
745 // Else default
746 return $this->_paymentProcessor['url_recur'];
747 }
748
749 }