CRM/Core/Payment/BaseIPN.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  * Class CRM_Core_Payment_BaseIPN.
  14  */
  15 class CRM_Core_Payment_BaseIPN {
  16
  17   public static $_now = NULL;
  18
  19   /**
  20    * Input parameters from payment processor. Store these so that
  21    * the code does not need to keep retrieving from the http request
  22    * @var array
  23    */
  24   protected $_inputParameters = [];
  25
  26   /**
  27    * Only used by AuthorizeNetIPN.
  28    * @var bool
  29    *
  30    * @deprecated
  31    *
  32    */
  33   protected $_isRecurring = FALSE;
  34
  35   /**
  36    * Only used by AuthorizeNetIPN.
  37    * @var bool
  38    *
  39    * @deprecated
  40    *
  41    */
  42   protected $_isFirstOrLastRecurringPayment = FALSE;
  43
  44   /**
  45    * Constructor.
  46    */
  47   public function __construct() {
  48     self::$_now = date('YmdHis');
  49   }
  50
  51   /**
  52    * Store input array on the class.
  53    *
  54    * @param array $parameters
  55    *
  56    * @throws CRM_Core_Exception
  57    */
  58   public function setInputParameters($parameters) {
  59     if (!is_array($parameters)) {
  60       throw new CRM_Core_Exception('Invalid input parameters');
  61     }
  62     $this->_inputParameters = $parameters;
  63   }
  64
  65   /**
  66    * Validate incoming data.
  67    *
  68    * This function is intended to ensure that incoming data matches
  69    * It provides a form of pseudo-authentication - by checking the calling fn already knows
  70    * the correct contact id & contribution id (this can be problematic when that has changed in
  71    * the meantime for transactions that are delayed & contacts are merged in-between. e.g
  72    * Paypal allows you to resend Instant Payment Notifications if you, for example, moved site
  73    * and didn't update your IPN URL.
  74    *
  75    * @param array $input
  76    *   Interpreted values from the values returned through the IPN.
  77    * @param array $ids
  78    *   More interpreted values (ids) from the values returned through the IPN.
  79    * @param array $objects
  80    *   An empty array that will be populated with loaded object.
  81    * @param bool $required
  82    *   Boolean Return FALSE if the relevant objects don't exist.
  83    * @param int $paymentProcessorID
  84    *   Id of the payment processor ID in use.
  85    *
  86    * @return bool
  87    */
  88   public function validateData(&$input, &$ids, &$objects, $required = TRUE, $paymentProcessorID = NULL) {
  89
  90     // make sure contact exists and is valid
  91     $contact = new CRM_Contact_BAO_Contact();
  92     $contact->id = $ids['contact'];
  93     if (!$contact->find(TRUE)) {
  94       CRM_Core_Error::debug_log_message("Could not find contact record: {$ids['contact']} in IPN request: " . print_r($input, TRUE));
  95       echo "Failure: Could not find contact record: {$ids['contact']}<p>";
  96       return FALSE;
  97     }
  98
  99     // make sure contribution exists and is valid
 100     $contribution = new CRM_Contribute_BAO_Contribution();
 101     $contribution->id = $ids['contribution'];
 102     if (!$contribution->find(TRUE)) {
 103       CRM_Core_Error::debug_log_message("Could not find contribution record: {$contribution->id} in IPN request: " . print_r($input, TRUE));
 104       echo "Failure: Could not find contribution record for {$contribution->id}<p>";
 105       return FALSE;
 106     }
 107     $contribution->receive_date = CRM_Utils_Date::isoToMysql($contribution->receive_date);
 108     $contribution->receipt_date = CRM_Utils_Date::isoToMysql($contribution->receipt_date);
 109
 110     $objects['contact'] = &$contact;
 111     $objects['contribution'] = &$contribution;
 112
 113     // CRM-19478: handle oddity when p=null is set in place of contribution page ID,
 114     if (!empty($ids['contributionPage']) && !is_numeric($ids['contributionPage'])) {
 115       // We don't need to worry if about removing contribution page id as it will be set later in
 116       //  CRM_Contribute_BAO_Contribution::loadRelatedObjects(..) using $objects['contribution']->contribution_page_id
 117       unset($ids['contributionPage']);
 118     }
 119
 120     if (!$this->loadObjects($input, $ids, $objects, $required, $paymentProcessorID)) {
 121       return FALSE;
 122     }
 123     //the process is that the loadObjects is kind of hacked by loading the objects for the original contribution and then somewhat inconsistently using them for the
 124     //current contribution. Here we ensure that the original contribution is available to the complete transaction function
 125     //we don't want to fix this in the payment processor classes because we would have to fix all of them - so better to fix somewhere central
 126     if (isset($objects['contributionRecur'])) {
 127       $objects['first_contribution'] = $objects['contribution'];
 128     }
 129     return TRUE;
 130   }
 131
 132   /**
 133    * Load objects related to contribution.
 134    *
 135    * @input array information from Payment processor
 136    *
 137    * @param array $input
 138    * @param array $ids
 139    * @param array $objects
 140    * @param bool $required
 141    * @param int $paymentProcessorID
 142    * @param array $error_handling
 143    *
 144    * @return bool|array
 145    */
 146   public function loadObjects(&$input, &$ids, &$objects, $required, $paymentProcessorID, $error_handling = NULL) {
 147     if (empty($error_handling)) {
 148       // default options are that we log an error & echo it out
 149       // note that we should refactor this error handling into error code @ some point
 150       // but for now setting up enough separation so we can do unit tests
 151       $error_handling = [
 152         'log_error' => 1,
 153         'echo_error' => 1,
 154       ];
 155     }
 156     $ids['paymentProcessor'] = $paymentProcessorID;
 157     if (is_a($objects['contribution'], 'CRM_Contribute_BAO_Contribution')) {
 158       $contribution = &$objects['contribution'];
 159     }
 160     else {
 161       //legacy support - functions are 'used' to be able to pass in a DAO
 162       $contribution = new CRM_Contribute_BAO_Contribution();
 163       $contribution->id = CRM_Utils_Array::value('contribution', $ids);
 164       $contribution->find(TRUE);
 165       $objects['contribution'] = &$contribution;
 166     }
 167     try {
 168       $success = $contribution->loadRelatedObjects($input, $ids);
 169       if ($required && empty($contribution->_relatedObjects['paymentProcessor'])) {
 170         throw new CRM_Core_Exception("Could not find payment processor for contribution record: " . $contribution->id);
 171       }
 172     }
 173     catch (Exception $e) {
 174       $success = FALSE;
 175       if (!empty($error_handling['log_error'])) {
 176         CRM_Core_Error::debug_log_message($e->getMessage());
 177       }
 178       if (!empty($error_handling['echo_error'])) {
 179         echo $e->getMessage();
 180       }
 181       if (!empty($error_handling['return_error'])) {
 182         return [
 183           'is_error' => 1,
 184           'error_message' => ($e->getMessage()),
 185         ];
 186       }
 187     }
 188     $objects = array_merge($objects, $contribution->_relatedObjects);
 189     return $success;
 190   }
 191
 192   /**
 193    * Set contribution to failed.
 194    *
 195    * @param array $objects
 196    * @param object $transaction
 197    * @param array $input
 198    *
 199    * @return bool
 200    * @throws \CiviCRM_API3_Exception
 201    */
 202   public function failed(&$objects, &$transaction, $input = []) {
 203     $contribution = &$objects['contribution'];
 204     $memberships = [];
 205     if (!empty($objects['membership'])) {
 206       $memberships = &$objects['membership'];
 207       if (is_numeric($memberships)) {
 208         $memberships = [$objects['membership']];
 209       }
 210     }
 211
 212     $addLineItems = FALSE;
 213     if (empty($contribution->id)) {
 214       $addLineItems = TRUE;
 215     }
 216     $participant = &$objects['participant'];
 217
 218     // CRM-15546
 219     $contributionStatuses = CRM_Core_PseudoConstant::get('CRM_Contribute_DAO_Contribution', 'contribution_status_id', [
 220       'labelColumn' => 'name',
 221       'flip' => 1,
 222     ]);
 223     $contribution->contribution_status_id = $contributionStatuses['Failed'];
 224     $contribution->receive_date = CRM_Utils_Date::isoToMysql($contribution->receive_date);
 225     $contribution->receipt_date = CRM_Utils_Date::isoToMysql($contribution->receipt_date);
 226     $contribution->thankyou_date = CRM_Utils_Date::isoToMysql($contribution->thankyou_date);
 227     $contribution->save();
 228
 229     // Add line items for recurring payments.
 230     if (!empty($objects['contributionRecur']) && $objects['contributionRecur']->id && $addLineItems) {
 231       CRM_Contribute_BAO_ContributionRecur::addRecurLineItems($objects['contributionRecur']->id, $contribution);
 232     }
 233
 234     //add new soft credit against current contribution id and
 235     //copy initial contribution custom fields for recurring contributions
 236     if (!empty($objects['contributionRecur']) && $objects['contributionRecur']->id) {
 237       CRM_Contribute_BAO_ContributionRecur::addrecurSoftCredit($objects['contributionRecur']->id, $contribution->id);
 238       CRM_Contribute_BAO_ContributionRecur::copyCustomValues($objects['contributionRecur']->id, $contribution->id);
 239     }
 240
 241     if (empty($input['IAmAHorribleNastyBeyondExcusableHackInTheCRMEventFORMTaskClassThatNeedsToBERemoved'])) {
 242       if (!empty($memberships)) {
 243         foreach ($memberships as $membership) {
 244           // @fixme Should we cancel only Pending memberships? per cancelled()
 245           $this->cancelMembership($membership, $membership->status_id, FALSE);
 246         }
 247       }
 248
 249       if ($participant) {
 250         $this->cancelParticipant($participant->id);
 251       }
 252     }
 253
 254     $transaction->commit();
 255     Civi::log()->debug("Setting contribution status to Failed");
 256     return TRUE;
 257   }
 258
 259   /**
 260    * Handled pending contribution status.
 261    *
 262    * @param array $objects
 263    * @param object $transaction
 264    *
 265    * @return bool
 266    */
 267   public function pending(&$objects, &$transaction) {
 268     $transaction->commit();
 269     Civi::log()->debug("Returning since contribution status is Pending");
 270     echo "Success: Returning since contribution status is pending<p>";
 271     return TRUE;
 272   }
 273
 274   /**
 275    * Process cancelled payment outcome.
 276    *
 277    * @param array $objects
 278    * @param CRM_Core_Transaction $transaction
 279    * @param array $input
 280    *
 281    * @return bool
 282    * @throws \CiviCRM_API3_Exception
 283    */
 284   public function cancelled(&$objects, &$transaction, $input = []) {
 285     $contribution = &$objects['contribution'];
 286     $memberships = [];
 287     if (!empty($objects['membership'])) {
 288       $memberships = &$objects['membership'];
 289       if (is_numeric($memberships)) {
 290         $memberships = [$objects['membership']];
 291       }
 292     }
 293
 294     $addLineItems = FALSE;
 295     if (empty($contribution->id)) {
 296       $addLineItems = TRUE;
 297     }
 298     $participant = &$objects['participant'];
 299
 300     // CRM-15546
 301     $contributionStatuses = CRM_Core_PseudoConstant::get('CRM_Contribute_DAO_Contribution', 'contribution_status_id', [
 302       'labelColumn' => 'name',
 303       'flip' => 1,
 304     ]);
 305     $contribution->contribution_status_id = $contributionStatuses['Cancelled'];
 306     $contribution->receive_date = CRM_Utils_Date::isoToMysql($contribution->receive_date);
 307     $contribution->receipt_date = CRM_Utils_Date::isoToMysql($contribution->receipt_date);
 308     $contribution->thankyou_date = CRM_Utils_Date::isoToMysql($contribution->thankyou_date);
 309     $contribution->cancel_date = self::$_now;
 310     $contribution->cancel_reason = CRM_Utils_Array::value('reasonCode', $input);
 311     $contribution->save();
 312
 313     // Add line items for recurring payments.
 314     if (!empty($objects['contributionRecur']) && $objects['contributionRecur']->id && $addLineItems) {
 315       CRM_Contribute_BAO_ContributionRecur::addRecurLineItems($objects['contributionRecur']->id, $contribution);
 316     }
 317
 318     //add new soft credit against current $contribution and
 319     //copy initial contribution custom fields for recurring contributions
 320     if (!empty($objects['contributionRecur']) && $objects['contributionRecur']->id) {
 321       CRM_Contribute_BAO_ContributionRecur::addrecurSoftCredit($objects['contributionRecur']->id, $contribution->id);
 322       CRM_Contribute_BAO_ContributionRecur::copyCustomValues($objects['contributionRecur']->id, $contribution->id);
 323     }
 324
 325     if (empty($input['IAmAHorribleNastyBeyondExcusableHackInTheCRMEventFORMTaskClassThatNeedsToBERemoved'])) {
 326       if (!empty($memberships)) {
 327         foreach ($memberships as $membership) {
 328           if ($membership) {
 329             $this->cancelMembership($membership, $membership->status_id);
 330           }
 331         }
 332       }
 333
 334       if ($participant) {
 335         $this->cancelParticipant($participant->id);
 336       }
 337     }
 338     $transaction->commit();
 339     Civi::log()->debug("Setting contribution status to Cancelled");
 340     return TRUE;
 341   }
 342
 343   /**
 344    * Rollback unhandled outcomes.
 345    *
 346    * @param array $objects
 347    * @param CRM_Core_Transaction $transaction
 348    *
 349    * @return bool
 350    */
 351   public function unhandled(&$objects, &$transaction) {
 352     $transaction->rollback();
 353     Civi::log()->debug("Returning since contribution status is not handled");
 354     echo "Failure: contribution status is not handled<p>";
 355     return FALSE;
 356   }
 357
 358   /**
 359    * Logic to cancel a participant record when the related contribution changes to failed/cancelled.
 360    * @todo This is part of a bigger refactor for dev/core/issues/927 - "duplicate" functionality exists in CRM_Contribute_BAO_Contribution::cancel()
 361    *
 362    * @param $participantID
 363    *
 364    * @throws \CiviCRM_API3_Exception
 365    */
 366   private function cancelParticipant($participantID) {
 367     // @fixme https://lab.civicrm.org/dev/core/issues/927 Cancelling membership etc is not desirable for all use-cases and we should be able to disable it
 368     $participantParams['id'] = $participantID;
 369     $participantParams['status_id'] = 'Cancelled';
 370     civicrm_api3('Participant', 'create', $participantParams);
 371   }
 372
 373   /**
 374    * Logic to cancel a membership record when the related contribution changes to failed/cancelled.
 375    * @todo This is part of a bigger refactor for dev/core/issues/927 - "duplicate" functionality exists in CRM_Contribute_BAO_Contribution::cancel()
 376    * @param \CRM_Member_BAO_Membership $membership
 377    * @param int $membershipStatusID
 378    * @param boolean $onlyCancelPendingMembership
 379    *   Do we only cancel pending memberships? OR memberships in any status? (see CRM-18688)
 380    * @fixme Historically failed() cancelled membership in any status, cancelled() cancelled only pending memberships so we retain that behaviour for now.
 381    *
 382    */
 383   private function cancelMembership($membership, $membershipStatusID, $onlyCancelPendingMembership = TRUE) {
 384     // @fixme https://lab.civicrm.org/dev/core/issues/927 Cancelling membership etc is not desirable for all use-cases and we should be able to disable it
 385     // Cancel only Pending memberships
 386     $pendingMembershipStatusId = CRM_Core_PseudoConstant::getKey('CRM_Member_BAO_Membership', 'status_id', 'Pending');
 387     if (($membershipStatusID == $pendingMembershipStatusId) || ($onlyCancelPendingMembership == FALSE)) {
 388       $cancelledMembershipStatusId = CRM_Core_PseudoConstant::getKey('CRM_Member_BAO_Membership', 'status_id', 'Cancelled');
 389
 390       $membership->status_id = $cancelledMembershipStatusId;
 391       $membership->save();
 392
 393       $params = ['status_id' => $cancelledMembershipStatusId];
 394       CRM_Member_BAO_Membership::updateRelatedMemberships($membership->id, $params);
 395
 396       // @todo Convert the above to API
 397       // $membershipParams = [
 398       //   'id' => $membership->id,
 399       //   'status_id' => $cancelledMembershipStatusId,
 400       // ];
 401       // civicrm_api3('Membership', 'create', $membershipParams);
 402       // CRM_Member_BAO_Membership::updateRelatedMemberships($membershipParams['id'], ['status_id' => $cancelledMembershipStatusId]);
 403     }
 404
 405   }
 406
 407   /**
 408    * @deprecated
 409    *
 410    * Jumbled up function.
 411    *
 412    * The purpose of this function is to transition a pending transaction to Completed including updating any
 413    * related entities.
 414    *
 415    * It has been overloaded to also add recurring transactions to the database, cloning the original transaction and
 416    * updating related entities.
 417    *
 418    * It is recommended to avoid calling this function directly and call the api functions:
 419    *  - contribution.completetransaction
 420    *  - contribution.repeattransaction
 421    *
 422    * These functions are the focus of testing efforts and more accurately reflect the division of roles
 423    * (the job of the IPN class is to determine the outcome, transaction id, invoice id & to validate the source
 424    * and from there it should be possible to pass off transaction management.)
 425    *
 426    * This function has been problematic for some time but there are now several tests via the api_v3_Contribution test
 427    * and the Paypal & Authorize.net IPN tests so any refactoring should be done in conjunction with those.
 428    *
 429    * This function needs to have the 'body' moved to the CRM_Contribute_BAO_Contribute class and to undergo
 430    * refactoring to separate the complete transaction and repeat transaction functionality into separate functions with
 431    * a shared function that updates related components.
 432    *
 433    * Note that it is not necessary payment processor extension to implement an IPN class now. In general the code on the
 434    * IPN class is better accessed through the api which de-jumbles it a bit.
 435    *
 436    * e.g the payment class can have a function like (based on Omnipay extension):
 437    *
 438    *   public function handlePaymentNotification() {
 439    *     $response = $this->getValidatedOutcome();
 440    *     if ($response->isSuccessful()) {
 441    *      try {
 442    *        // @todo check if it is a repeat transaction & call repeattransaction instead.
 443    *        civicrm_api3('contribution', 'completetransaction', array('id' => $this->transaction_id));
 444    *      }
 445    *     catch (CiviCRM_API3_Exception $e) {
 446    *     if (!stristr($e->getMessage(), 'Contribution already completed')) {
 447    *       $this->handleError('error', $this->transaction_id  . $e->getMessage(), 'ipn_completion', 9000, 'An error may
 448    *         have occurred. Please check your receipt is correct');
 449    *       $this->redirectOrExit('success');
 450    *     }
 451    *     elseif ($this->transaction_id) {
 452    *        civicrm_api3('contribution', 'create', array('id' => $this->transaction_id, 'contribution_status_id' =>
 453    *        'Failed'));
 454    *     }
 455    *
 456    * @param array $input
 457    * @param array $ids
 458    * @param array $objects
 459    * @param CRM_Core_Transaction $transaction
 460    *
 461    * @throws \CRM_Core_Exception
 462    * @throws \CiviCRM_API3_Exception
 463    */
 464   public function completeTransaction(&$input, &$ids, &$objects, &$transaction) {
 465     $contribution = &$objects['contribution'];
 466
 467     CRM_Contribute_BAO_Contribution::completeOrder($input, $ids, $objects, $transaction, $contribution);
 468   }
 469
 470   /**
 471    * Get site billing ID.
 472    *
 473    * @param array $ids
 474    *
 475    * @return bool
 476    */
 477   public function getBillingID(&$ids) {
 478     $ids['billing'] = CRM_Core_BAO_LocationType::getBilling();
 479     if (!$ids['billing']) {
 480       CRM_Core_Error::debug_log_message(ts('Please set a location type of %1', [1 => 'Billing']));
 481       echo "Failure: Could not find billing location type<p>";
 482       return FALSE;
 483     }
 484     return TRUE;
 485   }
 486
 487   /**
 488    * @deprecated
 489    *
 490    * @todo confirm this function is not being used by any payment processor outside core & remove.
 491    *
 492    * Note that the compose message part has been moved to contribution
 493    * In general LoadObjects is called first to get the objects but the composeMessageArray function now calls it
 494    *
 495    * @param array $input
 496    *   Incoming data from Payment processor.
 497    * @param array $ids
 498    *   Related object IDs.
 499    * @param array $objects
 500    * @param array $values
 501    *   Values related to objects that have already been loaded.
 502    * @param bool $recur
 503    *   Is it part of a recurring contribution.
 504    * @param bool $returnMessageText
 505    *   Should text be returned instead of sent. This.
 506    *   is because the function is also used to generate pdfs
 507    *
 508    * @return array
 509    * @throws \CRM_Core_Exception
 510    * @throws \CiviCRM_API3_Exception
 511    */
 512   public function sendMail(&$input, &$ids, &$objects, &$values, $recur = FALSE, $returnMessageText = FALSE) {
 513     return CRM_Contribute_BAO_Contribution::sendMail($input, $ids, $objects['contribution']->id, $values,
 514       $returnMessageText);
 515   }
 516
 517 }