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     // Check if the contribution exists
  91     // make sure contribution exists and is valid
  92     $contribution = new CRM_Contribute_BAO_Contribution();
  93     $contribution->id = $ids['contribution'];
  94     if (!$contribution->find(TRUE)) {
  95       CRM_Core_Error::debug_log_message("Could not find contribution record: {$contribution->id} in IPN request: " . print_r($input, TRUE));
  96       echo "Failure: Could not find contribution record for {$contribution->id}<p>";
  97       return FALSE;
  98     }
  99
 100     // make sure contact exists and is valid
 101     // use the contact id from the contribution record as the id in the IPN may not be valid anymore.
 102     $contact = new CRM_Contact_BAO_Contact();
 103     $contact->id = $contribution->contact_id;
 104     $contact->find(TRUE);
 105     if ($contact->id != $ids['contact']) {
 106       // If the ids do not match then it is possible the contact id in the IPN has been merged into another contact which is why we use the contact_id from the contribution
 107       CRM_Core_Error::debug_log_message("Contact ID in IPN {$ids['contact']} not found but contact_id found in contribution {$contribution->contact_id} used instead");
 108       echo "WARNING: Could not find contact record: {$ids['contact']}<p>";
 109       $ids['contact'] = $contribution->contact_id;
 110     }
 111
 112     if (!empty($ids['contributionRecur'])) {
 113       $contributionRecur = new CRM_Contribute_BAO_ContributionRecur();
 114       $contributionRecur->id = $ids['contributionRecur'];
 115       if (!$contributionRecur->find(TRUE)) {
 116         CRM_Core_Error::debug_log_message("Could not find contribution recur record: {$ids['ContributionRecur']} in IPN request: " . print_r($input, TRUE));
 117         echo "Failure: Could not find contribution recur record: {$ids['ContributionRecur']}<p>";
 118         return FALSE;
 119       }
 120     }
 121
 122     $contribution->receive_date = CRM_Utils_Date::isoToMysql($contribution->receive_date);
 123     $contribution->receipt_date = CRM_Utils_Date::isoToMysql($contribution->receipt_date);
 124
 125     $objects['contact'] = &$contact;
 126     $objects['contribution'] = &$contribution;
 127
 128     // CRM-19478: handle oddity when p=null is set in place of contribution page ID,
 129     if (!empty($ids['contributionPage']) && !is_numeric($ids['contributionPage'])) {
 130       // We don't need to worry if about removing contribution page id as it will be set later in
 131       //  CRM_Contribute_BAO_Contribution::loadRelatedObjects(..) using $objects['contribution']->contribution_page_id
 132       unset($ids['contributionPage']);
 133     }
 134
 135     if (!$this->loadObjects($input, $ids, $objects, $required, $paymentProcessorID)) {
 136       return FALSE;
 137     }
 138     //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
 139     //current contribution. Here we ensure that the original contribution is available to the complete transaction function
 140     //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
 141     if (isset($objects['contributionRecur'])) {
 142       $objects['first_contribution'] = $objects['contribution'];
 143     }
 144     return TRUE;
 145   }
 146
 147   /**
 148    * Load objects related to contribution.
 149    *
 150    * @input array information from Payment processor
 151    *
 152    * @param array $input
 153    * @param array $ids
 154    * @param array $objects
 155    * @param bool $required
 156    * @param int $paymentProcessorID
 157    * @param array $error_handling
 158    *
 159    * @return bool|array
 160    */
 161   public function loadObjects($input, &$ids, &$objects, $required, $paymentProcessorID, $error_handling = NULL) {
 162     if (empty($error_handling)) {
 163       // default options are that we log an error & echo it out
 164       // note that we should refactor this error handling into error code @ some point
 165       // but for now setting up enough separation so we can do unit tests
 166       $error_handling = [
 167         'log_error' => 1,
 168         'echo_error' => 1,
 169       ];
 170     }
 171     $ids['paymentProcessor'] = $paymentProcessorID;
 172     if (is_a($objects['contribution'], 'CRM_Contribute_BAO_Contribution')) {
 173       $contribution = &$objects['contribution'];
 174     }
 175     else {
 176       //legacy support - functions are 'used' to be able to pass in a DAO
 177       $contribution = new CRM_Contribute_BAO_Contribution();
 178       $contribution->id = $ids['contribution'] ?? NULL;
 179       $contribution->find(TRUE);
 180       $objects['contribution'] = &$contribution;
 181     }
 182     try {
 183       $success = $contribution->loadRelatedObjects($input, $ids);
 184       if ($required && empty($contribution->_relatedObjects['paymentProcessor'])) {
 185         throw new CRM_Core_Exception("Could not find payment processor for contribution record: " . $contribution->id);
 186       }
 187     }
 188     catch (Exception $e) {
 189       $success = FALSE;
 190       if (!empty($error_handling['log_error'])) {
 191         CRM_Core_Error::debug_log_message($e->getMessage());
 192       }
 193       if (!empty($error_handling['echo_error'])) {
 194         echo $e->getMessage();
 195       }
 196       if (!empty($error_handling['return_error'])) {
 197         return [
 198           'is_error' => 1,
 199           'error_message' => ($e->getMessage()),
 200         ];
 201       }
 202     }
 203     $objects = array_merge($objects, $contribution->_relatedObjects);
 204     return $success;
 205   }
 206
 207   /**
 208    * Set contribution to failed.
 209    *
 210    * @param array $objects
 211    * @param object $transaction
 212    * @param array $input
 213    *
 214    * @return bool
 215    * @throws \CiviCRM_API3_Exception
 216    */
 217   public function failed(&$objects, $transaction = NULL, $input = []) {
 218     $contribution = &$objects['contribution'];
 219     $memberships = [];
 220     if (!empty($objects['membership'])) {
 221       $memberships = &$objects['membership'];
 222       if (is_numeric($memberships)) {
 223         $memberships = [$objects['membership']];
 224       }
 225     }
 226
 227     $addLineItems = empty($contribution->id);
 228     $participant = &$objects['participant'];
 229     $contribution->contribution_status_id = CRM_Core_PseudoConstant::getKey('CRM_Contribute_DAO_Contribution', 'contribution_status_id', 'Failed');
 230     $contribution->save();
 231
 232     // Add line items for recurring payments.
 233     if (!empty($objects['contributionRecur']) && $objects['contributionRecur']->id && $addLineItems) {
 234       CRM_Contribute_BAO_ContributionRecur::addRecurLineItems($objects['contributionRecur']->id, $contribution);
 235     }
 236
 237     //add new soft credit against current contribution id and
 238     //copy initial contribution custom fields for recurring contributions
 239     if (!empty($objects['contributionRecur']) && $objects['contributionRecur']->id) {
 240       CRM_Contribute_BAO_ContributionRecur::addrecurSoftCredit($objects['contributionRecur']->id, $contribution->id);
 241       CRM_Contribute_BAO_ContributionRecur::copyCustomValues($objects['contributionRecur']->id, $contribution->id);
 242     }
 243
 244     if (empty($input['IAmAHorribleNastyBeyondExcusableHackInTheCRMEventFORMTaskClassThatNeedsToBERemoved'])) {
 245       if (!empty($memberships)) {
 246         foreach ($memberships as $membership) {
 247           // @fixme Should we cancel only Pending memberships? per cancelled()
 248           $this->cancelMembership($membership, $membership->status_id, FALSE);
 249         }
 250       }
 251
 252       if ($participant) {
 253         $this->cancelParticipant($participant->id);
 254       }
 255     }
 256
 257     if ($transaction) {
 258       $transaction->commit();
 259     }
 260     Civi::log()->debug("Setting contribution status to Failed");
 261     return TRUE;
 262   }
 263
 264   /**
 265    * Handled pending contribution status.
 266    *
 267    * @deprecated
 268    *
 269    * @param array $objects
 270    * @param object $transaction
 271    *
 272    * @return bool
 273    */
 274   public function pending(&$objects, &$transaction) {
 275     CRM_Core_Error::deprecatedFunctionWarning('This function will be removed at some point');
 276     $transaction->commit();
 277     Civi::log()->debug('Returning since contribution status is Pending');
 278     echo 'Success: Returning since contribution status is pending<p>';
 279     return TRUE;
 280   }
 281
 282   /**
 283    * Process cancelled payment outcome.
 284    *
 285    * @param array $objects
 286    * @param CRM_Core_Transaction $transaction
 287    * @param array $input
 288    *
 289    * @return bool
 290    * @throws \CiviCRM_API3_Exception
 291    */
 292   public function cancelled(&$objects, $transaction = NULL, $input = []) {
 293     $contribution = &$objects['contribution'];
 294     $memberships = [];
 295     if (!empty($objects['membership'])) {
 296       $memberships = &$objects['membership'];
 297       if (is_numeric($memberships)) {
 298         $memberships = [$objects['membership']];
 299       }
 300     }
 301
 302     $addLineItems = FALSE;
 303     if (empty($contribution->id)) {
 304       $addLineItems = TRUE;
 305     }
 306     $participant = &$objects['participant'];
 307
 308     // CRM-15546
 309     $contributionStatuses = CRM_Core_PseudoConstant::get('CRM_Contribute_DAO_Contribution', 'contribution_status_id', [
 310       'labelColumn' => 'name',
 311       'flip' => 1,
 312     ]);
 313     $contribution->contribution_status_id = $contributionStatuses['Cancelled'];
 314     $contribution->receive_date = CRM_Utils_Date::isoToMysql($contribution->receive_date);
 315     $contribution->receipt_date = CRM_Utils_Date::isoToMysql($contribution->receipt_date);
 316     $contribution->thankyou_date = CRM_Utils_Date::isoToMysql($contribution->thankyou_date);
 317     $contribution->cancel_date = self::$_now;
 318     $contribution->cancel_reason = $input['reasonCode'] ?? NULL;
 319     $contribution->save();
 320
 321     // Add line items for recurring payments.
 322     if (!empty($objects['contributionRecur']) && $objects['contributionRecur']->id && $addLineItems) {
 323       CRM_Contribute_BAO_ContributionRecur::addRecurLineItems($objects['contributionRecur']->id, $contribution);
 324     }
 325
 326     //add new soft credit against current $contribution and
 327     //copy initial contribution custom fields for recurring contributions
 328     if (!empty($objects['contributionRecur']) && $objects['contributionRecur']->id) {
 329       CRM_Contribute_BAO_ContributionRecur::addrecurSoftCredit($objects['contributionRecur']->id, $contribution->id);
 330       CRM_Contribute_BAO_ContributionRecur::copyCustomValues($objects['contributionRecur']->id, $contribution->id);
 331     }
 332
 333     if (empty($input['IAmAHorribleNastyBeyondExcusableHackInTheCRMEventFORMTaskClassThatNeedsToBERemoved'])) {
 334       if (!empty($memberships)) {
 335         foreach ($memberships as $membership) {
 336           if ($membership) {
 337             $this->cancelMembership($membership, $membership->status_id);
 338           }
 339         }
 340       }
 341
 342       if ($participant) {
 343         $this->cancelParticipant($participant->id);
 344       }
 345     }
 346     if ($transaction) {
 347       $transaction->commit();
 348     }
 349     Civi::log()->debug("Setting contribution status to Cancelled");
 350     return TRUE;
 351   }
 352
 353   /**
 354    * Rollback unhandled outcomes.
 355    *
 356    * @deprecated
 357    *
 358    * @param array $objects
 359    * @param CRM_Core_Transaction $transaction
 360    *
 361    * @return bool
 362    */
 363   public function unhandled(&$objects, &$transaction) {
 364     CRM_Core_Error::deprecatedFunctionWarning('This function will be removed at some point');
 365     $transaction->rollback();
 366     Civi::log()->debug('Returning since contribution status is not handled');
 367     echo 'Failure: contribution status is not handled<p>';
 368     return FALSE;
 369   }
 370
 371   /**
 372    * Logic to cancel a participant record when the related contribution changes to failed/cancelled.
 373    * @todo This is part of a bigger refactor for dev/core/issues/927 - "duplicate" functionality exists in CRM_Contribute_BAO_Contribution::cancel()
 374    *
 375    * @param $participantID
 376    *
 377    * @throws \CiviCRM_API3_Exception
 378    */
 379   private function cancelParticipant($participantID) {
 380     // @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
 381     $participantParams['id'] = $participantID;
 382     $participantParams['status_id'] = 'Cancelled';
 383     civicrm_api3('Participant', 'create', $participantParams);
 384   }
 385
 386   /**
 387    * Logic to cancel a membership record when the related contribution changes to failed/cancelled.
 388    * @todo This is part of a bigger refactor for dev/core/issues/927 - "duplicate" functionality exists in CRM_Contribute_BAO_Contribution::cancel()
 389    * @param \CRM_Member_BAO_Membership $membership
 390    * @param int $membershipStatusID
 391    * @param boolean $onlyCancelPendingMembership
 392    *   Do we only cancel pending memberships? OR memberships in any status? (see CRM-18688)
 393    * @fixme Historically failed() cancelled membership in any status, cancelled() cancelled only pending memberships so we retain that behaviour for now.
 394    *
 395    */
 396   private function cancelMembership($membership, $membershipStatusID, $onlyCancelPendingMembership = TRUE) {
 397     // @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
 398     // Cancel only Pending memberships
 399     $pendingMembershipStatusId = CRM_Core_PseudoConstant::getKey('CRM_Member_BAO_Membership', 'status_id', 'Pending');
 400     if (($membershipStatusID == $pendingMembershipStatusId) || ($onlyCancelPendingMembership == FALSE)) {
 401       $cancelledMembershipStatusId = CRM_Core_PseudoConstant::getKey('CRM_Member_BAO_Membership', 'status_id', 'Cancelled');
 402
 403       $membership->status_id = $cancelledMembershipStatusId;
 404       $membership->save();
 405
 406       $params = ['status_id' => $cancelledMembershipStatusId];
 407       CRM_Member_BAO_Membership::updateRelatedMemberships($membership->id, $params);
 408
 409       // @todo Convert the above to API
 410       // $membershipParams = [
 411       //   'id' => $membership->id,
 412       //   'status_id' => $cancelledMembershipStatusId,
 413       // ];
 414       // civicrm_api3('Membership', 'create', $membershipParams);
 415       // CRM_Member_BAO_Membership::updateRelatedMemberships($membershipParams['id'], ['status_id' => $cancelledMembershipStatusId]);
 416     }
 417
 418   }
 419
 420   /**
 421    * @deprecated
 422    *
 423    * Jumbled up function.
 424    *
 425    * The purpose of this function is to transition a pending transaction to Completed including updating any
 426    * related entities.
 427    *
 428    * It has been overloaded to also add recurring transactions to the database, cloning the original transaction and
 429    * updating related entities.
 430    *
 431    * It is recommended to avoid calling this function directly and call the api functions:
 432    *  - contribution.completetransaction
 433    *  - contribution.repeattransaction
 434    *
 435    * These functions are the focus of testing efforts and more accurately reflect the division of roles
 436    * (the job of the IPN class is to determine the outcome, transaction id, invoice id & to validate the source
 437    * and from there it should be possible to pass off transaction management.)
 438    *
 439    * This function has been problematic for some time but there are now several tests via the api_v3_Contribution test
 440    * and the Paypal & Authorize.net IPN tests so any refactoring should be done in conjunction with those.
 441    *
 442    * This function needs to have the 'body' moved to the CRM_Contribute_BAO_Contribute class and to undergo
 443    * refactoring to separate the complete transaction and repeat transaction functionality into separate functions with
 444    * a shared function that updates related components.
 445    *
 446    * Note that it is not necessary payment processor extension to implement an IPN class now. In general the code on the
 447    * IPN class is better accessed through the api which de-jumbles it a bit.
 448    *
 449    * e.g the payment class can have a function like (based on Omnipay extension):
 450    *
 451    *   public function handlePaymentNotification() {
 452    *     $response = $this->getValidatedOutcome();
 453    *     if ($response->isSuccessful()) {
 454    *      try {
 455    *        // @todo check if it is a repeat transaction & call repeattransaction instead.
 456    *        civicrm_api3('contribution', 'completetransaction', array('id' => $this->transaction_id));
 457    *      }
 458    *     catch (CiviCRM_API3_Exception $e) {
 459    *     if (!stristr($e->getMessage(), 'Contribution already completed')) {
 460    *       $this->handleError('error', $this->transaction_id  . $e->getMessage(), 'ipn_completion', 9000, 'An error may
 461    *         have occurred. Please check your receipt is correct');
 462    *       $this->redirectOrExit('success');
 463    *     }
 464    *     elseif ($this->transaction_id) {
 465    *        civicrm_api3('contribution', 'create', array('id' => $this->transaction_id, 'contribution_status_id' =>
 466    *        'Failed'));
 467    *     }
 468    *
 469    * @param array $input
 470    * @param array $ids
 471    * @param array $objects
 472    *
 473    * @throws \CRM_Core_Exception
 474    * @throws \CiviCRM_API3_Exception
 475    */
 476   public function completeTransaction(&$input, &$ids, &$objects) {
 477     CRM_Contribute_BAO_Contribution::completeOrder($input, $ids, $objects);
 478   }
 479
 480   /**
 481    * @deprecated
 482    * Get site billing ID.
 483    *
 484    * @param array $ids
 485    *
 486    * @return bool
 487    */
 488   public function getBillingID(&$ids) {
 489     CRM_Core_Error::deprecatedFunctionWarning('CRM_Core_BAO_LocationType::getBilling()');
 490     $ids['billing'] = CRM_Core_BAO_LocationType::getBilling();
 491     if (!$ids['billing']) {
 492       CRM_Core_Error::debug_log_message(ts('Please set a location type of %1', [1 => 'Billing']));
 493       echo "Failure: Could not find billing location type<p>";
 494       return FALSE;
 495     }
 496     return TRUE;
 497   }
 498
 499   /**
 500    * @deprecated
 501    *
 502    * @todo confirm this function is not being used by any payment processor outside core & remove.
 503    *
 504    * Note that the compose message part has been moved to contribution
 505    * In general LoadObjects is called first to get the objects but the composeMessageArray function now calls it
 506    *
 507    * @param array $input
 508    *   Incoming data from Payment processor.
 509    * @param array $ids
 510    *   Related object IDs.
 511    * @param array $objects
 512    *
 513    * @throws \CiviCRM_API3_Exception
 514    */
 515   public function sendMail($input, $ids, $objects) {
 516     CRM_Core_Error::deprecatedFunctionWarning('this should be done via completetransaction api');
 517     civicrm_api3('Contribution', 'sendconfirmation', [
 518       'id' => $objects['contribution']->id,
 519     ]);
 520   }
 521
 522 }