CRM/Core/Payment.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.7                                                |
   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 use Civi\Payment\Exception\PaymentProcessorException;
  30
  31 /**
  32  * Class CRM_Core_Payment.
  33  *
  34  * This class is the main class for the payment processor subsystem.
  35  *
  36  * It is the parent class for payment processors. It also holds some IPN related functions
  37  * that need to be moved. In particular handlePaymentMethod should be moved to a factory class.
  38  */
  39 abstract class CRM_Core_Payment {
  40
  41   /**
  42    * Component - ie. event or contribute.
  43    *
  44    * This is used for setting return urls.
  45    *
  46    * @var string
  47    */
  48   protected $_component;
  49
  50   /**
  51    * How are we getting billing information.
  52    *
  53    * We are trying to completely deprecate these parameters.
  54    *
  55    * FORM   - we collect it on the same page
  56    * BUTTON - the processor collects it and sends it back to us via some protocol
  57    */
  58   const
  59     BILLING_MODE_FORM = 1,
  60     BILLING_MODE_BUTTON = 2,
  61     BILLING_MODE_NOTIFY = 4;
  62
  63   /**
  64    * Which payment type(s) are we using?
  65    *
  66    * credit card
  67    * direct debit
  68    * or both
  69    * @todo create option group - nb omnipay uses a 3rd type - transparent redirect cc
  70    */
  71   const
  72     PAYMENT_TYPE_CREDIT_CARD = 1,
  73     PAYMENT_TYPE_DIRECT_DEBIT = 2;
  74
  75   /**
  76    * Subscription / Recurring payment Status
  77    * START, END
  78    */
  79   const
  80     RECURRING_PAYMENT_START = 'START',
  81     RECURRING_PAYMENT_END = 'END';
  82
  83   protected $_paymentProcessor;
  84
  85   /**
  86    * Base url of the calling form.
  87    *
  88    * This is used for processors that need to return the browser back to the CiviCRM site.
  89    *
  90    * @var string
  91    */
  92   protected $baseReturnUrl;
  93
  94   /**
  95    * The profile configured to show on the billing form.
  96    *
  97    * Currently only the pseudo-profile 'billing' is supported but hopefully in time we will take an id and
  98    * load that from the DB and the processor will be able to return a set of fields that combines it's minimum
  99    * requirements with the configured requirements.
 100    *
 101    * Currently only the pseudo-processor 'manual' or 'pay-later' uses this setting to return a 'curated' set
 102    * of fields.
 103    *
 104    * Note this change would probably include converting 'billing' to a reserved profile.
 105    *
 106    * @var int|string
 107    */
 108   protected $billingProfile;
 109
 110   /**
 111    * Set Base return URL.
 112    *
 113    * @param string $url
 114    *   Url of site to return browser to.
 115    */
 116   public function setBaseReturnUrl($url) {
 117     $this->baseReturnUrl = $url;
 118   }
 119
 120   /**
 121    * Set the configured payment profile.
 122    *
 123    * @param int|string $value
 124    */
 125   public function setBillingProfile($value) {
 126     $this->billingProfile = $value;
 127   }
 128
 129   /**
 130    * Opportunity for the payment processor to override the entire form build.
 131    *
 132    * @param CRM_Core_Form $form
 133    *
 134    * @return bool
 135    *   Should form building stop at this point?
 136    */
 137   public function buildForm(&$form) {
 138     return FALSE;
 139   }
 140
 141   /**
 142    * Log payment notification message to forensic system log.
 143    *
 144    * @todo move to factory class \Civi\Payment\System (or similar)
 145    *
 146    * @param array $params
 147    *
 148    * @return mixed
 149    */
 150   public static function logPaymentNotification($params) {
 151     $message = 'payment_notification ';
 152     if (!empty($params['processor_name'])) {
 153       $message .= 'processor_name=' . $params['processor_name'];
 154     }
 155     if (!empty($params['processor_id'])) {
 156       $message .= 'processor_id=' . $params['processor_id'];
 157     }
 158
 159     $log = new CRM_Utils_SystemLogger();
 160     $log->alert($message, $_REQUEST);
 161   }
 162
 163   /**
 164    * Check if capability is supported.
 165    *
 166    * Capabilities have a one to one relationship with capability-related functions on this class.
 167    *
 168    * Payment processor classes should over-ride the capability-specific function rather than this one.
 169    *
 170    * @param string $capability
 171    *   E.g BackOffice, LiveMode, FutureRecurStartDate.
 172    *
 173    * @return bool
 174    */
 175   public function supports($capability) {
 176     $function = 'supports' . ucfirst($capability);
 177     if (method_exists($this, $function)) {
 178       return $this->$function();
 179     }
 180     return FALSE;
 181   }
 182
 183   /**
 184    * Are back office payments supported.
 185    *
 186    * e.g paypal standard won't permit you to enter a credit card associated
 187    * with someone else's login.
 188    * The intention is to support off-site (other than paypal) & direct debit but that is not all working yet so to
 189    * reach a 'stable' point we disable.
 190    *
 191    * @return bool
 192    */
 193   protected function supportsBackOffice() {
 194     if ($this->_paymentProcessor['billing_mode'] == 4 || $this->_paymentProcessor['payment_type'] != 1) {
 195       return FALSE;
 196     }
 197     else {
 198       return TRUE;
 199     }
 200   }
 201
 202   /**
 203    * Can more than one transaction be processed at once?
 204    *
 205    * In general processors that process payment by server to server communication support this while others do not.
 206    *
 207    * In future we are likely to hit an issue where this depends on whether a token already exists.
 208    *
 209    * @return bool
 210    */
 211   protected function supportsMultipleConcurrentPayments() {
 212     if ($this->_paymentProcessor['billing_mode'] == 4 || $this->_paymentProcessor['payment_type'] != 1) {
 213       return FALSE;
 214     }
 215     else {
 216       return TRUE;
 217     }
 218   }
 219
 220   /**
 221    * Are live payments supported - e.g dummy doesn't support this.
 222    *
 223    * @return bool
 224    */
 225   protected function supportsLiveMode() {
 226     return TRUE;
 227   }
 228
 229   /**
 230    * Are test payments supported.
 231    *
 232    * @return bool
 233    */
 234   protected function supportsTestMode() {
 235     return TRUE;
 236   }
 237
 238   /**
 239    * Should the first payment date be configurable when setting up back office recurring payments.
 240    *
 241    * We set this to false for historical consistency but in fact most new processors use tokens for recurring and can support this
 242    *
 243    * @return bool
 244    */
 245   protected function supportsFutureRecurStartDate() {
 246     return FALSE;
 247   }
 248
 249   /**
 250    * Does this processor support cancelling recurring contributions through code.
 251    *
 252    * If the processor returns true it must be possible to take action from within CiviCRM
 253    * that will result in no further payments being processed. In the case of token processors (e.g
 254    * IATS, eWay) updating the contribution_recur table is probably sufficient.
 255    *
 256    * @return bool
 257    */
 258   protected function supportsCancelRecurring() {
 259     return method_exists(CRM_Utils_System::getClassName($this), 'cancelSubscription');
 260   }
 261
 262   /**
 263    * Does this processor support pre-approval.
 264    *
 265    * This would generally look like a redirect to enter credentials which can then be used in a later payment call.
 266    *
 267    * Currently Paypal express supports this, with a redirect to paypal after the 'Main' form is submitted in the
 268    * contribution page. This token can then be processed at the confirm phase. Although this flow 'looks' like the
 269    * 'notify' flow a key difference is that in the notify flow they don't have to return but in this flow they do.
 270    *
 271    * @return bool
 272    */
 273   protected function supportsPreApproval() {
 274     return FALSE;
 275   }
 276
 277   /**
 278    * Can recurring contributions be set against pledges.
 279    *
 280    * In practice all processors that use the baseIPN function to finish transactions or
 281    * call the completetransaction api support this by looking up previous contributions in the
 282    * series and, if there is a prior contribution against a pledge, and the pledge is not complete,
 283    * adding the new payment to the pledge.
 284    *
 285    * However, only enabling for processors it has been tested against.
 286    *
 287    * @return bool
 288    */
 289   protected function supportsRecurContributionsForPledges() {
 290     return FALSE;
 291   }
 292
 293   /**
 294    * Function to action pre-approval if supported
 295    *
 296    * @param array $params
 297    *   Parameters from the form
 298    *
 299    * This function returns an array which should contain
 300    *   - pre_approval_parameters (this will be stored on the calling form & available later)
 301    *   - redirect_url (if set the browser will be redirected to this.
 302    */
 303   public function doPreApproval(&$params) {}
 304
 305   /**
 306    * Get any details that may be available to the payment processor due to an approval process having happened.
 307    *
 308    * In some cases the browser is redirected to enter details on a processor site. Some details may be available as a
 309    * result.
 310    *
 311    * @param array $storedDetails
 312    *
 313    * @return array
 314    */
 315   public function getPreApprovalDetails($storedDetails) {
 316     return array();
 317   }
 318
 319   /**
 320    * Default payment instrument validation.
 321    *
 322    * Implement the usual Luhn algorithm via a static function in the CRM_Core_Payment_Form if it's a credit card
 323    * Not a static function, because I need to check for payment_type.
 324    *
 325    * @param array $values
 326    * @param array $errors
 327    */
 328   public function validatePaymentInstrument($values, &$errors) {
 329     CRM_Core_Form::validateMandatoryFields($this->getMandatoryFields(), $values, $errors);
 330     if ($this->_paymentProcessor['payment_type'] == 1) {
 331       CRM_Core_Payment_Form::validateCreditCard($values, $errors);
 332     }
 333   }
 334
 335   /**
 336    * Getter for the payment processor.
 337    *
 338    * The payment processor array is based on the civicrm_payment_processor table entry.
 339    *
 340    * @return array
 341    *   Payment processor array.
 342    */
 343   public function getPaymentProcessor() {
 344     return $this->_paymentProcessor;
 345   }
 346
 347   /**
 348    * Setter for the payment processor.
 349    *
 350    * @param array $processor
 351    */
 352   public function setPaymentProcessor($processor) {
 353     $this->_paymentProcessor = $processor;
 354   }
 355
 356   /**
 357    * Setter for the payment form that wants to use the processor.
 358    *
 359    * @deprecated
 360    *
 361    * @param CRM_Core_Form $paymentForm
 362    */
 363   public function setForm(&$paymentForm) {
 364     $this->_paymentForm = $paymentForm;
 365   }
 366
 367   /**
 368    * Getter for payment form that is using the processor.
 369    * @deprecated
 370    * @return CRM_Core_Form
 371    *   A form object
 372    */
 373   public function getForm() {
 374     return $this->_paymentForm;
 375   }
 376
 377   /**
 378    * Getter for accessing member vars.
 379    *
 380    * @todo believe this is unused
 381    *
 382    * @param string $name
 383    *
 384    * @return null
 385    */
 386   public function getVar($name) {
 387     return isset($this->$name) ? $this->$name : NULL;
 388   }
 389
 390   /**
 391    * Get name for the payment information type.
 392    * @todo - use option group + name field (like Omnipay does)
 393    * @return string
 394    */
 395   public function getPaymentTypeName() {
 396     return $this->_paymentProcessor['payment_type'] == 1 ? 'credit_card' : 'direct_debit';
 397   }
 398
 399   /**
 400    * Get label for the payment information type.
 401    * @todo - use option group + labels (like Omnipay does)
 402    * @return string
 403    */
 404   public function getPaymentTypeLabel() {
 405     return $this->_paymentProcessor['payment_type'] == 1 ? 'Credit Card' : 'Direct Debit';
 406   }
 407
 408   /**
 409    * Get array of fields that should be displayed on the payment form.
 410    * @todo make payment type an option value & use it in the function name - currently on debit & credit card work
 411    * @return array
 412    * @throws CiviCRM_API3_Exception
 413    */
 414   public function getPaymentFormFields() {
 415     if ($this->_paymentProcessor['billing_mode'] == 4) {
 416       return array();
 417     }
 418     return $this->_paymentProcessor['payment_type'] == 1 ? $this->getCreditCardFormFields() : $this->getDirectDebitFormFields();
 419   }
 420
 421   /**
 422    * Get the metadata for all required fields.
 423    *
 424    * @return array;
 425    */
 426   protected function getMandatoryFields() {
 427     $mandatoryFields = array();
 428     foreach ($this->getAllFields() as $field_name => $field_spec) {
 429       if (!empty($field_spec['is_required'])) {
 430         $mandatoryFields[$field_name] = $field_spec;
 431       }
 432     }
 433     return $mandatoryFields;
 434   }
 435
 436   /**
 437    * Get the metadata of all the fields configured for this processor.
 438    *
 439    * @return array
 440    */
 441   protected function getAllFields() {
 442     $paymentFields = array_intersect_key($this->getPaymentFormFieldsMetadata(), array_flip($this->getPaymentFormFields()));
 443     $billingFields = array_intersect_key($this->getBillingAddressFieldsMetadata(), array_flip($this->getBillingAddressFields()));
 444     return array_merge($paymentFields, $billingFields);
 445   }
 446   /**
 447    * Get array of fields that should be displayed on the payment form for credit cards.
 448    *
 449    * @return array
 450    */
 451   protected function getCreditCardFormFields() {
 452     return array(
 453       'credit_card_type',
 454       'credit_card_number',
 455       'cvv2',
 456       'credit_card_exp_date',
 457     );
 458   }
 459
 460   /**
 461    * Get array of fields that should be displayed on the payment form for direct debits.
 462    *
 463    * @return array
 464    */
 465   protected function getDirectDebitFormFields() {
 466     return array(
 467       'account_holder',
 468       'bank_account_number',
 469       'bank_identification_number',
 470       'bank_name',
 471     );
 472   }
 473
 474   /**
 475    * Return an array of all the details about the fields potentially required for payment fields.
 476    *
 477    * Only those determined by getPaymentFormFields will actually be assigned to the form
 478    *
 479    * @return array
 480    *   field metadata
 481    */
 482   public function getPaymentFormFieldsMetadata() {
 483     //@todo convert credit card type into an option value
 484     $creditCardType = array('' => ts('- select -')) + CRM_Contribute_PseudoConstant::creditCard();
 485     return array(
 486       'credit_card_number' => array(
 487         'htmlType' => 'text',
 488         'name' => 'credit_card_number',
 489         'title' => ts('Card Number'),
 490         'cc_field' => TRUE,
 491         'attributes' => array(
 492           'size' => 20,
 493           'maxlength' => 20,
 494           'autocomplete' => 'off',
 495           'class' => 'creditcard',
 496         ),
 497         'is_required' => TRUE,
 498       ),
 499       'cvv2' => array(
 500         'htmlType' => 'text',
 501         'name' => 'cvv2',
 502         'title' => ts('Security Code'),
 503         'cc_field' => TRUE,
 504         'attributes' => array(
 505           'size' => 5,
 506           'maxlength' => 10,
 507           'autocomplete' => 'off',
 508         ),
 509         'is_required' => Civi::settings()->get('cvv_backoffice_required'),
 510         'rules' => array(
 511           array(
 512             '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.'),
 513             'rule_name' => 'integer',
 514             'rule_parameters' => NULL,
 515           ),
 516         ),
 517       ),
 518       'credit_card_exp_date' => array(
 519         'htmlType' => 'date',
 520         'name' => 'credit_card_exp_date',
 521         'title' => ts('Expiration Date'),
 522         'cc_field' => TRUE,
 523         'attributes' => CRM_Core_SelectValues::date('creditCard'),
 524         'is_required' => TRUE,
 525         'rules' => array(
 526           array(
 527             'rule_message' => ts('Card expiration date cannot be a past date.'),
 528             'rule_name' => 'currentDate',
 529             'rule_parameters' => TRUE,
 530           ),
 531         ),
 532       ),
 533       'credit_card_type' => array(
 534         'htmlType' => 'select',
 535         'name' => 'credit_card_type',
 536         'title' => ts('Card Type'),
 537         'cc_field' => TRUE,
 538         'attributes' => $creditCardType,
 539         'is_required' => FALSE,
 540       ),
 541       'account_holder' => array(
 542         'htmlType' => 'text',
 543         'name' => 'account_holder',
 544         'title' => ts('Account Holder'),
 545         'cc_field' => TRUE,
 546         'attributes' => array(
 547           'size' => 20,
 548           'maxlength' => 34,
 549           'autocomplete' => 'on',
 550         ),
 551         'is_required' => TRUE,
 552       ),
 553       //e.g. IBAN can have maxlength of 34 digits
 554       'bank_account_number' => array(
 555         'htmlType' => 'text',
 556         'name' => 'bank_account_number',
 557         'title' => ts('Bank Account Number'),
 558         'cc_field' => TRUE,
 559         'attributes' => array(
 560           'size' => 20,
 561           'maxlength' => 34,
 562           'autocomplete' => 'off',
 563         ),
 564         'rules' => array(
 565           array(
 566             'rule_message' => ts('Please enter a valid Bank Identification Number (value must not contain punctuation characters).'),
 567             'rule_name' => 'nopunctuation',
 568             'rule_parameters' => NULL,
 569           ),
 570         ),
 571         'is_required' => TRUE,
 572       ),
 573       //e.g. SWIFT-BIC can have maxlength of 11 digits
 574       'bank_identification_number' => array(
 575         'htmlType' => 'text',
 576         'name' => 'bank_identification_number',
 577         'title' => ts('Bank Identification Number'),
 578         'cc_field' => TRUE,
 579         'attributes' => array(
 580           'size' => 20,
 581           'maxlength' => 11,
 582           'autocomplete' => 'off',
 583         ),
 584         'is_required' => TRUE,
 585         'rules' => array(
 586           array(
 587             'rule_message' => ts('Please enter a valid Bank Identification Number (value must not contain punctuation characters).'),
 588             'rule_name' => 'nopunctuation',
 589             'rule_parameters' => NULL,
 590           ),
 591         ),
 592       ),
 593       'bank_name' => array(
 594         'htmlType' => 'text',
 595         'name' => 'bank_name',
 596         'title' => ts('Bank Name'),
 597         'cc_field' => TRUE,
 598         'attributes' => array(
 599           'size' => 20,
 600           'maxlength' => 64,
 601           'autocomplete' => 'off',
 602         ),
 603         'is_required' => TRUE,
 604
 605       ),
 606     );
 607   }
 608
 609   /**
 610    * Get billing fields required for this processor.
 611    *
 612    * We apply the existing default of returning fields only for payment processor type 1. Processors can override to
 613    * alter.
 614    *
 615    * @param int $billingLocationID
 616    *
 617    * @return array
 618    */
 619   public function getBillingAddressFields($billingLocationID = NULL) {
 620     if (!$billingLocationID) {
 621       // Note that although the billing id is passed around the forms the idea that it would be anything other than
 622       // the result of the function below doesn't seem to have eventuated.
 623       // So taking this as a param is possibly something to be removed in favour of the standard default.
 624       $billingLocationID = CRM_Core_BAO_LocationType::getBilling();
 625     }
 626     if ($this->_paymentProcessor['billing_mode'] != 1 && $this->_paymentProcessor['billing_mode'] != 3) {
 627       return array();
 628     }
 629     return array(
 630       'first_name' => 'billing_first_name',
 631       'middle_name' => 'billing_middle_name',
 632       'last_name' => 'billing_last_name',
 633       'street_address' => "billing_street_address-{$billingLocationID}",
 634       'city' => "billing_city-{$billingLocationID}",
 635       'country' => "billing_country_id-{$billingLocationID}",
 636       'state_province' => "billing_state_province_id-{$billingLocationID}",
 637       'postal_code' => "billing_postal_code-{$billingLocationID}",
 638     );
 639   }
 640
 641   /**
 642    * Get form metadata for billing address fields.
 643    *
 644    * @param int $billingLocationID
 645    *
 646    * @return array
 647    *    Array of metadata for address fields.
 648    */
 649   public function getBillingAddressFieldsMetadata($billingLocationID = NULL) {
 650     if (!$billingLocationID) {
 651       // Note that although the billing id is passed around the forms the idea that it would be anything other than
 652       // the result of the function below doesn't seem to have eventuated.
 653       // So taking this as a param is possibly something to be removed in favour of the standard default.
 654       $billingLocationID = CRM_Core_BAO_LocationType::getBilling();
 655     }
 656     $metadata = array();
 657     $metadata['billing_first_name'] = array(
 658       'htmlType' => 'text',
 659       'name' => 'billing_first_name',
 660       'title' => ts('Billing First Name'),
 661       'cc_field' => TRUE,
 662       'attributes' => array(
 663         'size' => 30,
 664         'maxlength' => 60,
 665         'autocomplete' => 'off',
 666       ),
 667       'is_required' => TRUE,
 668     );
 669
 670     $metadata['billing_middle_name'] = array(
 671       'htmlType' => 'text',
 672       'name' => 'billing_middle_name',
 673       'title' => ts('Billing Middle Name'),
 674       'cc_field' => TRUE,
 675       'attributes' => array(
 676         'size' => 30,
 677         'maxlength' => 60,
 678         'autocomplete' => 'off',
 679       ),
 680       'is_required' => FALSE,
 681     );
 682
 683     $metadata['billing_last_name'] = array(
 684       'htmlType' => 'text',
 685       'name' => 'billing_last_name',
 686       'title' => ts('Billing Last Name'),
 687       'cc_field' => TRUE,
 688       'attributes' => array(
 689         'size' => 30,
 690         'maxlength' => 60,
 691         'autocomplete' => 'off',
 692       ),
 693       'is_required' => TRUE,
 694     );
 695
 696     $metadata["billing_street_address-{$billingLocationID}"] = array(
 697       'htmlType' => 'text',
 698       'name' => "billing_street_address-{$billingLocationID}",
 699       'title' => ts('Street Address'),
 700       'cc_field' => TRUE,
 701       'attributes' => array(
 702         'size' => 30,
 703         'maxlength' => 60,
 704         'autocomplete' => 'off',
 705       ),
 706       'is_required' => TRUE,
 707     );
 708
 709     $metadata["billing_city-{$billingLocationID}"] = array(
 710       'htmlType' => 'text',
 711       'name' => "billing_city-{$billingLocationID}",
 712       'title' => ts('City'),
 713       'cc_field' => TRUE,
 714       'attributes' => array(
 715         'size' => 30,
 716         'maxlength' => 60,
 717         'autocomplete' => 'off',
 718       ),
 719       'is_required' => TRUE,
 720     );
 721
 722     $metadata["billing_state_province_id-{$billingLocationID}"] = array(
 723       'htmlType' => 'chainSelect',
 724       'title' => ts('State/Province'),
 725       'name' => "billing_state_province_id-{$billingLocationID}",
 726       'cc_field' => TRUE,
 727       'is_required' => TRUE,
 728     );
 729
 730     $metadata["billing_postal_code-{$billingLocationID}"] = array(
 731       'htmlType' => 'text',
 732       'name' => "billing_postal_code-{$billingLocationID}",
 733       'title' => ts('Postal Code'),
 734       'cc_field' => TRUE,
 735       'attributes' => array(
 736         'size' => 30,
 737         'maxlength' => 60,
 738         'autocomplete' => 'off',
 739       ),
 740       'is_required' => TRUE,
 741     );
 742
 743     $metadata["billing_country_id-{$billingLocationID}"] = array(
 744       'htmlType' => 'select',
 745       'name' => "billing_country_id-{$billingLocationID}",
 746       'title' => ts('Country'),
 747       'cc_field' => TRUE,
 748       'attributes' => array(
 749         '' => ts('- select -'),
 750       ) + CRM_Core_PseudoConstant::country(),
 751       'is_required' => TRUE,
 752     );
 753     return $metadata;
 754   }
 755
 756   /**
 757    * Get base url dependent on component.
 758    *
 759    * (or preferably set it using the setter function).
 760    *
 761    * @return string
 762    */
 763   protected function getBaseReturnUrl() {
 764     if ($this->baseReturnUrl) {
 765       return $this->baseReturnUrl;
 766     }
 767     if ($this->_component == 'event') {
 768       $baseURL = 'civicrm/event/register';
 769     }
 770     else {
 771       $baseURL = 'civicrm/contribute/transact';
 772     }
 773     return $baseURL;
 774   }
 775
 776   /**
 777    * Get url to return to after cancelled or failed transaction
 778    *
 779    * @param $qfKey
 780    * @param $participantID
 781    *
 782    * @return string cancel url
 783    */
 784   public function getCancelUrl($qfKey, $participantID) {
 785     if ($this->_component == 'event') {
 786       return CRM_Utils_System::url($this->getBaseReturnUrl(), array(
 787         'reset' => 1,
 788         'cc' => 'fail',
 789         'participantId' => $participantID,
 790       ),
 791         TRUE, NULL, FALSE
 792       );
 793     }
 794
 795     return CRM_Utils_System::url($this->getBaseReturnUrl(), array(
 796       '_qf_Main_display' => 1,
 797       'qfKey' => $qfKey,
 798       'cancel' => 1,
 799     ),
 800       TRUE, NULL, FALSE
 801     );
 802   }
 803
 804   /**
 805    * Get URL to return the browser to on success.
 806    *
 807    * @param $qfKey
 808    *
 809    * @return string
 810    */
 811   protected function getReturnSuccessUrl($qfKey) {
 812     return CRM_Utils_System::url($this->getBaseReturnUrl(), array(
 813       '_qf_ThankYou_display' => 1,
 814       'qfKey' => $qfKey,
 815     ),
 816       TRUE, NULL, FALSE
 817     );
 818   }
 819
 820   /**
 821    * Get URL to return the browser to on failure.
 822    *
 823    * @param string $key
 824    * @param int $participantID
 825    * @param int $eventID
 826    *
 827    * @return string
 828    *   URL for a failing transactor to be redirected to.
 829    */
 830   protected function getReturnFailUrl($key, $participantID = NULL, $eventID = NULL) {
 831     $test = $this->_is_test ? '&action=preview' : '';
 832     if ($this->_component == "event") {
 833       return CRM_Utils_System::url('civicrm/event/register',
 834         "reset=1&cc=fail&participantId={$participantID}&id={$eventID}{$test}&qfKey={$key}",
 835         FALSE, NULL, FALSE
 836       );
 837     }
 838     else {
 839       return CRM_Utils_System::url('civicrm/contribute/transact',
 840         "_qf_Main_display=1&cancel=1&qfKey={$key}{$test}",
 841         FALSE, NULL, FALSE
 842       );
 843     }
 844   }
 845
 846   /**
 847    * Get URl for when the back button is pressed.
 848    *
 849    * @param $qfKey
 850    *
 851    * @return string url
 852    */
 853   protected function getGoBackUrl($qfKey) {
 854     return CRM_Utils_System::url($this->getBaseReturnUrl(), array(
 855       '_qf_Confirm_display' => 'true',
 856       'qfKey' => $qfKey,
 857     ),
 858       TRUE, NULL, FALSE
 859     );
 860   }
 861
 862   /**
 863    * Get the notify (aka ipn, web hook or silent post) url.
 864    *
 865    * If there is no '.' in it we assume that we are dealing with localhost or
 866    * similar and it is unreachable from the web & hence invalid.
 867    *
 868    * @return string
 869    *   URL to notify outcome of transaction.
 870    */
 871   protected function getNotifyUrl() {
 872     $url = CRM_Utils_System::url(
 873       'civicrm/payment/ipn/' . $this->_paymentProcessor['id'],
 874       array(),
 875       TRUE
 876     );
 877     return (stristr($url, '.')) ? $url : '';
 878   }
 879
 880   /**
 881    * Calling this from outside the payment subsystem is deprecated - use doPayment.
 882    *
 883    * Does a server to server payment transaction.
 884    *
 885    * @param array $params
 886    *   Assoc array of input parameters for this transaction.
 887    *
 888    * @return array
 889    *   the result in an nice formatted array (or an error object - but throwing exceptions is preferred)
 890    */
 891   protected function doDirectPayment(&$params) {
 892     return $params;
 893   }
 894
 895   /**
 896    * Process payment - this function wraps around both doTransferPayment and doDirectPayment.
 897    *
 898    * The function ensures an exception is thrown & moves some of this logic out of the form layer and makes the forms
 899    * more agnostic.
 900    *
 901    * Payment processors should set payment_status_id. This function adds some historical defaults ie. the
 902    * assumption that if a 'doDirectPayment' processors comes back it completed the transaction & in fact
 903    * doTransferCheckout would not traditionally come back.
 904    *
 905    * doDirectPayment does not do an immediate payment for Authorize.net or Paypal so the default is assumed
 906    * to be Pending.
 907    *
 908    * Once this function is fully rolled out then it will be preferred for processors to throw exceptions than to
 909    * return Error objects
 910    *
 911    * @param array $params
 912    *
 913    * @param string $component
 914    *
 915    * @return array
 916    *   Result array
 917    *
 918    * @throws \Civi\Payment\Exception\PaymentProcessorException
 919    */
 920   public function doPayment(&$params, $component = 'contribute') {
 921     $this->_component = $component;
 922     $statuses = CRM_Contribute_BAO_Contribution::buildOptions('contribution_status_id');
 923
 924     // If we have a $0 amount, skip call to processor and set payment_status to Completed.
 925     // Conceivably a processor might override this - perhaps for setting up a token - but we don't
 926     // have an example of that at the mome.
 927     if ($params['amount'] == 0) {
 928       $result['payment_status_id'] = array_search('Completed', $statuses);
 929       return $result;
 930     }
 931
 932     if ($this->_paymentProcessor['billing_mode'] == 4) {
 933       $result = $this->doTransferCheckout($params, $component);
 934       if (is_array($result) && !isset($result['payment_status_id'])) {
 935         $result['payment_status_id'] = array_search('Pending', $statuses);
 936       }
 937     }
 938     else {
 939       $result = $this->doDirectPayment($params, $component);
 940       if (is_array($result) && !isset($result['payment_status_id'])) {
 941         if (!empty($params['is_recur'])) {
 942           // See comment block.
 943           $result['payment_status_id'] = array_search('Pending', $statuses);
 944         }
 945         else {
 946           $result['payment_status_id'] = array_search('Completed', $statuses);
 947         }
 948       }
 949     }
 950     if (is_a($result, 'CRM_Core_Error')) {
 951       throw new PaymentProcessorException(CRM_Core_Error::getMessages($result));
 952     }
 953     return $result;
 954   }
 955
 956   /**
 957    * Query payment processor for details about a transaction.
 958    *
 959    * @param array $params
 960    *   Array of parameters containing one of:
 961    *   - trxn_id Id of an individual transaction.
 962    *   - processor_id Id of a recurring contribution series as stored in the civicrm_contribution_recur table.
 963    *
 964    * @return array
 965    *   Extra parameters retrieved.
 966    *   Any parameters retrievable through this should be documented in the function comments at
 967    *   CRM_Core_Payment::doQuery. Currently:
 968    *   - fee_amount Amount of fee paid
 969    */
 970   public function doQuery($params) {
 971     return array();
 972   }
 973
 974   /**
 975    * This function checks to see if we have the right config values.
 976    *
 977    * @return string
 978    *   the error message if any
 979    */
 980   abstract protected function checkConfig();
 981
 982   /**
 983    * Redirect for paypal.
 984    *
 985    * @todo move to paypal class or remove
 986    *
 987    * @param $paymentProcessor
 988    *
 989    * @return bool
 990    */
 991   public static function paypalRedirect(&$paymentProcessor) {
 992     if (!$paymentProcessor) {
 993       return FALSE;
 994     }
 995
 996     if (isset($_GET['payment_date']) &&
 997       isset($_GET['merchant_return_link']) &&
 998       CRM_Utils_Array::value('payment_status', $_GET) == 'Completed' &&
 999       $paymentProcessor['payment_processor_type'] == "PayPal_Standard"
1000     ) {
1001       return TRUE;
1002     }
1003
1004     return FALSE;
1005   }
1006
1007   /**
1008    * Handle incoming payment notification.
1009    *
1010    * IPNs, also called silent posts are notifications of payment outcomes or activity on an external site.
1011    *
1012    * @todo move to0 \Civi\Payment\System factory method
1013    * Page callback for civicrm/payment/ipn
1014    */
1015   public static function handleIPN() {
1016     self::handlePaymentMethod(
1017       'PaymentNotification',
1018       array(
1019         'processor_name' => @$_GET['processor_name'],
1020         'processor_id' => @$_GET['processor_id'],
1021         'mode' => @$_GET['mode'],
1022         'q' => @$_GET['q'],
1023       )
1024     );
1025     CRM_Utils_System::civiExit();
1026   }
1027
1028   /**
1029    * Payment callback handler.
1030    *
1031    * The processor_name or processor_id is passed in.
1032    * Note that processor_id is more reliable as one site may have more than one instance of a
1033    * processor & ideally the processor will be validating the results
1034    * Load requested payment processor and call that processor's handle<$method> method
1035    *
1036    * @todo move to \Civi\Payment\System factory method
1037    *
1038    * @param string $method
1039    *   'PaymentNotification' or 'PaymentCron'
1040    * @param array $params
1041    *
1042    * @throws \CRM_Core_Exception
1043    * @throws \Exception
1044    */
1045   public static function handlePaymentMethod($method, $params = array()) {
1046     if (!isset($params['processor_id']) && !isset($params['processor_name'])) {
1047       $q = explode('/', CRM_Utils_Array::value('q', $params, ''));
1048       $lastParam = array_pop($q);
1049       if (is_numeric($lastParam)) {
1050         $params['processor_id'] = $_GET['processor_id'] = $lastParam;
1051       }
1052       else {
1053         throw new CRM_Core_Exception("Either 'processor_id' (recommended) or 'processor_name' (deprecated) is required for payment callback.");
1054       }
1055     }
1056
1057     self::logPaymentNotification($params);
1058
1059     $sql = "SELECT ppt.class_name, ppt.name as processor_name, pp.id AS processor_id
1060               FROM civicrm_payment_processor_type ppt
1061         INNER JOIN civicrm_payment_processor pp
1062                 ON pp.payment_processor_type_id = ppt.id
1063                AND pp.is_active";
1064
1065     if (isset($params['processor_id'])) {
1066       $sql .= " WHERE pp.id = %2";
1067       $args[2] = array($params['processor_id'], 'Integer');
1068       $notFound = ts("No active instances of payment processor %1 were found.", array(1 => $params['processor_id']));
1069     }
1070     else {
1071       // This is called when processor_name is passed - passing processor_id instead is recommended.
1072       $sql .= " WHERE ppt.name = %2 AND pp.is_test = %1";
1073       $args[1] = array(
1074         (CRM_Utils_Array::value('mode', $params) == 'test') ? 1 : 0,
1075         'Integer',
1076       );
1077       $args[2] = array($params['processor_name'], 'String');
1078       $notFound = ts("No active instances of payment processor '%1' were found.", array(1 => $params['processor_name']));
1079     }
1080
1081     $dao = CRM_Core_DAO::executeQuery($sql, $args);
1082
1083     // Check whether we found anything at all.
1084     if (!$dao->N) {
1085       CRM_Core_Error::fatal($notFound);
1086     }
1087
1088     $method = 'handle' . $method;
1089     $extension_instance_found = FALSE;
1090
1091     // In all likelihood, we'll just end up with the one instance returned here. But it's
1092     // possible we may get more. Hence, iterate through all instances ..
1093
1094     while ($dao->fetch()) {
1095       // Check pp is extension - is this still required - surely the singleton below handles it.
1096       $ext = CRM_Extension_System::singleton()->getMapper();
1097       if ($ext->isExtensionKey($dao->class_name)) {
1098         $paymentClass = $ext->keyToClass($dao->class_name, 'payment');
1099         require_once $ext->classToPath($paymentClass);
1100       }
1101
1102       $processorInstance = System::singleton()->getById($dao->processor_id);
1103
1104       // Should never be empty - we already established this processor_id exists and is active.
1105       if (empty($processorInstance)) {
1106         continue;
1107       }
1108
1109       // Does PP implement this method, and can we call it?
1110       if (!method_exists($processorInstance, $method) ||
1111         !is_callable(array($processorInstance, $method))
1112       ) {
1113         // on the off chance there is a double implementation of this processor we should keep looking for another
1114         // note that passing processor_id is more reliable & we should work to deprecate processor_name
1115         continue;
1116       }
1117
1118       // Everything, it seems, is ok - execute pp callback handler
1119       $processorInstance->$method();
1120       $extension_instance_found = TRUE;
1121     }
1122
1123     if (!$extension_instance_found) {
1124       $message = "No extension instances of the '%1' payment processor were found.<br />" .
1125         "%2 method is unsupported in legacy payment processors.";
1126       CRM_Core_Error::fatal(ts($message, array(1 => $params['processor_name'], 2 => $method)));
1127     }
1128   }
1129
1130   /**
1131    * Check whether a method is present ( & supported ) by the payment processor object.
1132    *
1133    * @deprecated - use $paymentProcessor->supports(array('cancelRecurring');
1134    *
1135    * @param string $method
1136    *   Method to check for.
1137    *
1138    * @return bool
1139    */
1140   public function isSupported($method) {
1141     return method_exists(CRM_Utils_System::getClassName($this), $method);
1142   }
1143
1144   /**
1145    * Some processors replace the form submit button with their own.
1146    *
1147    * Returning false here will leave the button off front end forms.
1148    *
1149    * At this stage there is zero cross-over between back-office processors and processors that suppress the submit.
1150    */
1151   public function isSuppressSubmitButtons() {
1152     return FALSE;
1153   }
1154
1155   /**
1156    * Checks to see if invoice_id already exists in db.
1157    *
1158    * It's arguable if this belongs in the payment subsystem at all but since several processors implement it
1159    * it is better to standardise to being here.
1160    *
1161    * @param int $invoiceId The ID to check.
1162    *
1163    * @param null $contributionID
1164    *   If a contribution exists pass in the contribution ID.
1165    *
1166    * @return bool
1167    *   True if invoice ID otherwise exists, else false
1168    */
1169   protected function checkDupe($invoiceId, $contributionID = NULL) {
1170     $contribution = new CRM_Contribute_DAO_Contribution();
1171     $contribution->invoice_id = $invoiceId;
1172     if ($contributionID) {
1173       $contribution->whereAdd("id <> $contributionID");
1174     }
1175     return $contribution->find();
1176   }
1177
1178   /**
1179    * Get url for users to manage this recurring contribution for this processor.
1180    *
1181    * @param int $entityID
1182    * @param null $entity
1183    * @param string $action
1184    *
1185    * @return string
1186    */
1187   public function subscriptionURL($entityID = NULL, $entity = NULL, $action = 'cancel') {
1188     // Set URL
1189     switch ($action) {
1190       case 'cancel':
1191         $url = 'civicrm/contribute/unsubscribe';
1192         break;
1193
1194       case 'billing':
1195         //in notify mode don't return the update billing url
1196         if (!$this->isSupported('updateSubscriptionBillingInfo')) {
1197           return NULL;
1198         }
1199         $url = 'civicrm/contribute/updatebilling';
1200         break;
1201
1202       case 'update':
1203         $url = 'civicrm/contribute/updaterecur';
1204         break;
1205     }
1206
1207     $userId = CRM_Core_Session::singleton()->get('userID');
1208     $contactID = 0;
1209     $checksumValue = '';
1210     $entityArg = '';
1211
1212     // Find related Contact
1213     if ($entityID) {
1214       switch ($entity) {
1215         case 'membership':
1216           $contactID = CRM_Core_DAO::getFieldValue("CRM_Member_DAO_Membership", $entityID, "contact_id");
1217           $entityArg = 'mid';
1218           break;
1219
1220         case 'contribution':
1221           $contactID = CRM_Core_DAO::getFieldValue("CRM_Contribute_DAO_Contribution", $entityID, "contact_id");
1222           $entityArg = 'coid';
1223           break;
1224
1225         case 'recur':
1226           $sql = "
1227     SELECT con.contact_id
1228       FROM civicrm_contribution_recur rec
1229 INNER JOIN civicrm_contribution con ON ( con.contribution_recur_id = rec.id )
1230      WHERE rec.id = %1
1231   GROUP BY rec.id";
1232           $contactID = CRM_Core_DAO::singleValueQuery($sql, array(1 => array($entityID, 'Integer')));
1233           $entityArg = 'crid';
1234           break;
1235       }
1236     }
1237
1238     // Add entity arguments
1239     if ($entityArg != '') {
1240       // Add checksum argument
1241       if ($contactID != 0 && $userId != $contactID) {
1242         $checksumValue = '&cs=' . CRM_Contact_BAO_Contact_Utils::generateChecksum($contactID, NULL, 'inf');
1243       }
1244       return CRM_Utils_System::url($url, "reset=1&{$entityArg}={$entityID}{$checksumValue}", TRUE, NULL, FALSE, TRUE);
1245     }
1246
1247     // Else login URL
1248     if ($this->isSupported('accountLoginURL')) {
1249       return $this->accountLoginURL();
1250     }
1251
1252     // Else default
1253     return isset($this->_paymentProcessor['url_recur']) ? $this->_paymentProcessor['url_recur'] : '';
1254   }
1255
1256   /**
1257    * Get description of payment to pass to processor.
1258    *
1259    * This is often what people see in the interface so we want to get
1260    * as much unique information in as possible within the field length (& presumably the early part of the field)
1261    *
1262    * People seeing these can be assumed to be advanced users so quantity of information probably trumps
1263    * having field names to clarify
1264    *
1265    * @param array $params
1266    * @param int $length
1267    *
1268    * @return string
1269    */
1270   protected function getPaymentDescription($params, $length = 24) {
1271     $parts = array('contactID', 'contributionID', 'description', 'billing_first_name', 'billing_last_name');
1272     $validParts = array();
1273     if (isset($params['description'])) {
1274       $uninformativeStrings = array(ts('Online Event Registration: '), ts('Online Contribution: '));
1275       $params['description'] = str_replace($uninformativeStrings, '', $params['description']);
1276     }
1277     foreach ($parts as $part) {
1278       if ((!empty($params[$part]))) {
1279         $validParts[] = $params[$part];
1280       }
1281     }
1282     return substr(implode('-', $validParts), 0, $length);
1283   }
1284
1285   /**
1286    * Checks if backoffice recurring edit is allowed
1287    *
1288    * @return bool
1289    */
1290   public function supportsEditRecurringContribution() {
1291     return FALSE;
1292   }
1293
1294 }