3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
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 +--------------------------------------------------------------------+
13 * Class CRM_Core_Payment_BaseIPN.
15 class CRM_Core_Payment_BaseIPN
{
17 public static $_now = NULL;
20 * Input parameters from payment processor. Store these so that
21 * the code does not need to keep retrieving from the http request
24 protected $_inputParameters = [];
27 * Only used by AuthorizeNetIPN.
33 protected $_isRecurring = FALSE;
36 * Only used by AuthorizeNetIPN.
42 protected $_isFirstOrLastRecurringPayment = FALSE;
47 public function __construct() {
48 self
::$_now = date('YmdHis');
52 * Store input array on the class.
54 * @param array $parameters
56 * @throws CRM_Core_Exception
58 public function setInputParameters($parameters) {
59 if (!is_array($parameters)) {
60 throw new CRM_Core_Exception('Invalid input parameters');
62 $this->_inputParameters
= $parameters;
66 * Validate incoming data.
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.
76 * Interpreted values from the values returned through the IPN.
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.
88 public function validateData(&$input, &$ids, &$objects, $required = TRUE, $paymentProcessorID = NULL) {
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>";
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>";
107 $contribution->receive_date
= CRM_Utils_Date
::isoToMysql($contribution->receive_date
);
108 $contribution->receipt_date
= CRM_Utils_Date
::isoToMysql($contribution->receipt_date
);
110 $objects['contact'] = &$contact;
111 $objects['contribution'] = &$contribution;
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']);
120 if (!$this->loadObjects($input, $ids, $objects, $required, $paymentProcessorID)) {
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'];
133 * Load objects related to contribution.
135 * @input array information from Payment processor
137 * @param array $input
139 * @param array $objects
140 * @param bool $required
141 * @param int $paymentProcessorID
142 * @param array $error_handling
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
156 $ids['paymentProcessor'] = $paymentProcessorID;
157 if (is_a($objects['contribution'], 'CRM_Contribute_BAO_Contribution')) {
158 $contribution = &$objects['contribution'];
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;
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
);
173 catch (Exception
$e) {
175 if (!empty($error_handling['log_error'])) {
176 CRM_Core_Error
::debug_log_message($e->getMessage());
178 if (!empty($error_handling['echo_error'])) {
179 echo $e->getMessage();
181 if (!empty($error_handling['return_error'])) {
184 'error_message' => ($e->getMessage()),
188 $objects = array_merge($objects, $contribution->_relatedObjects
);
193 * Set contribution to failed.
195 * @param array $objects
196 * @param object $transaction
197 * @param array $input
200 * @throws \CiviCRM_API3_Exception
202 public function failed(&$objects, &$transaction, $input = []) {
203 $contribution = &$objects['contribution'];
205 if (!empty($objects['membership'])) {
206 $memberships = &$objects['membership'];
207 if (is_numeric($memberships)) {
208 $memberships = [$objects['membership']];
212 $addLineItems = FALSE;
213 if (empty($contribution->id
)) {
214 $addLineItems = TRUE;
216 $participant = &$objects['participant'];
219 $contributionStatuses = CRM_Core_PseudoConstant
::get('CRM_Contribute_DAO_Contribution', 'contribution_status_id', [
220 'labelColumn' => 'name',
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();
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);
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
);
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);
250 $this->cancelParticipant($participant->id
);
254 $transaction->commit();
255 Civi
::log()->debug("Setting contribution status to Failed");
260 * Handled pending contribution status.
262 * @param array $objects
263 * @param object $transaction
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>";
275 * Process cancelled payment outcome.
277 * @param array $objects
278 * @param CRM_Core_Transaction $transaction
279 * @param array $input
282 * @throws \CiviCRM_API3_Exception
284 public function cancelled(&$objects, &$transaction, $input = []) {
285 $contribution = &$objects['contribution'];
287 if (!empty($objects['membership'])) {
288 $memberships = &$objects['membership'];
289 if (is_numeric($memberships)) {
290 $memberships = [$objects['membership']];
294 $addLineItems = FALSE;
295 if (empty($contribution->id
)) {
296 $addLineItems = TRUE;
298 $participant = &$objects['participant'];
301 $contributionStatuses = CRM_Core_PseudoConstant
::get('CRM_Contribute_DAO_Contribution', 'contribution_status_id', [
302 'labelColumn' => 'name',
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();
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);
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
);
325 if (empty($input['IAmAHorribleNastyBeyondExcusableHackInTheCRMEventFORMTaskClassThatNeedsToBERemoved'])) {
326 if (!empty($memberships)) {
327 foreach ($memberships as $membership) {
329 $this->cancelMembership($membership, $membership->status_id
);
335 $this->cancelParticipant($participant->id
);
338 $transaction->commit();
339 Civi
::log()->debug("Setting contribution status to Cancelled");
344 * Rollback unhandled outcomes.
346 * @param array $objects
347 * @param CRM_Core_Transaction $transaction
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>";
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()
362 * @param $participantID
364 * @throws \CiviCRM_API3_Exception
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);
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.
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');
390 $membership->status_id
= $cancelledMembershipStatusId;
393 $params = ['status_id' => $cancelledMembershipStatusId];
394 CRM_Member_BAO_Membership
::updateRelatedMemberships($membership->id
, $params);
396 // @todo Convert the above to API
397 // $membershipParams = [
398 // 'id' => $membership->id,
399 // 'status_id' => $cancelledMembershipStatusId,
401 // civicrm_api3('Membership', 'create', $membershipParams);
402 // CRM_Member_BAO_Membership::updateRelatedMemberships($membershipParams['id'], ['status_id' => $cancelledMembershipStatusId]);
410 * Jumbled up function.
412 * The purpose of this function is to transition a pending transaction to Completed including updating any
415 * It has been overloaded to also add recurring transactions to the database, cloning the original transaction and
416 * updating related entities.
418 * It is recommended to avoid calling this function directly and call the api functions:
419 * - contribution.completetransaction
420 * - contribution.repeattransaction
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.)
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.
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.
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.
436 * e.g the payment class can have a function like (based on Omnipay extension):
438 * public function handlePaymentNotification() {
439 * $response = $this->getValidatedOutcome();
440 * if ($response->isSuccessful()) {
442 * // @todo check if it is a repeat transaction & call repeattransaction instead.
443 * civicrm_api3('contribution', 'completetransaction', array('id' => $this->transaction_id));
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');
451 * elseif ($this->transaction_id) {
452 * civicrm_api3('contribution', 'create', array('id' => $this->transaction_id, 'contribution_status_id' =>
456 * @param array $input
458 * @param array $objects
459 * @param CRM_Core_Transaction $transaction
461 * @throws \CRM_Core_Exception
462 * @throws \CiviCRM_API3_Exception
464 public function completeTransaction(&$input, &$ids, &$objects, &$transaction) {
465 $contribution = &$objects['contribution'];
467 CRM_Contribute_BAO_Contribution
::completeOrder($input, $ids, $objects, $transaction, $contribution);
471 * Get site billing ID.
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>";
490 * @todo confirm this function is not being used by any payment processor outside core & remove.
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
495 * @param array $input
496 * Incoming data from Payment processor.
498 * Related object IDs.
499 * @param array $objects
500 * @param array $values
501 * Values related to objects that have already been loaded.
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
509 * @throws \CRM_Core_Exception
510 * @throws \CiviCRM_API3_Exception
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,