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 +--------------------------------------------------------------------+
12 use Civi\Api4\Contribution
;
15 * Class CRM_Core_Payment_BaseIPN.
17 class CRM_Core_Payment_BaseIPN
{
19 public static $_now = NULL;
22 * Input parameters from payment processor. Store these so that
23 * the code does not need to keep retrieving from the http request
26 protected $_inputParameters = [];
29 * Only used by AuthorizeNetIPN.
35 protected $_isRecurring = FALSE;
38 * Only used by AuthorizeNetIPN.
44 protected $_isFirstOrLastRecurringPayment = FALSE;
49 public function __construct() {
50 self
::$_now = date('YmdHis');
54 * Store input array on the class.
56 * @param array $parameters
58 * @throws CRM_Core_Exception
60 public function setInputParameters($parameters) {
61 if (!is_array($parameters)) {
62 throw new CRM_Core_Exception('Invalid input parameters');
64 $this->_inputParameters
= $parameters;
68 * Validate incoming data.
70 * This function is intended to ensure that incoming data matches
71 * It provides a form of pseudo-authentication - by checking the calling fn already knows
72 * the correct contact id & contribution id (this can be problematic when that has changed in
73 * the meantime for transactions that are delayed & contacts are merged in-between. e.g
74 * Paypal allows you to resend Instant Payment Notifications if you, for example, moved site
75 * and didn't update your IPN URL.
78 * Interpreted values from the values returned through the IPN.
80 * More interpreted values (ids) from the values returned through the IPN.
81 * @param array $objects
82 * An empty array that will be populated with loaded object.
83 * @param bool $required
84 * Boolean Return FALSE if the relevant objects don't exist.
85 * @param int $paymentProcessorID
86 * Id of the payment processor ID in use.
92 public function validateData($input, &$ids, &$objects, $required = TRUE, $paymentProcessorID = NULL) {
93 CRM_Core_Error
::deprecatedFunctionWarning('unused');
94 // Check if the contribution exists
95 // make sure contribution exists and is valid
96 $contribution = new CRM_Contribute_BAO_Contribution();
97 $contribution->id
= $ids['contribution'];
98 if (!$contribution->find(TRUE)) {
99 throw new CRM_Core_Exception('Failure: Could not find contribution record for ' . (int) $contribution->id
, NULL, ['context' => "Could not find contribution record: {$contribution->id} in IPN request: " . print_r($input, TRUE)]);
102 // make sure contact exists and is valid
103 // use the contact id from the contribution record as the id in the IPN may not be valid anymore.
104 $contact = new CRM_Contact_BAO_Contact();
105 $contact->id
= $contribution->contact_id
;
106 $contact->find(TRUE);
107 if ($contact->id
!= $ids['contact']) {
108 // 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
109 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");
110 echo "WARNING: Could not find contact record: {$ids['contact']}<p>";
111 $ids['contact'] = $contribution->contact_id
;
114 if (!empty($ids['contributionRecur'])) {
115 $contributionRecur = new CRM_Contribute_BAO_ContributionRecur();
116 $contributionRecur->id
= $ids['contributionRecur'];
117 if (!$contributionRecur->find(TRUE)) {
118 CRM_Core_Error
::debug_log_message("Could not find contribution recur record: {$ids['ContributionRecur']} in IPN request: " . print_r($input, TRUE));
119 echo "Failure: Could not find contribution recur record: {$ids['ContributionRecur']}<p>";
124 $objects['contact'] = &$contact;
125 $objects['contribution'] = &$contribution;
127 // CRM-19478: handle oddity when p=null is set in place of contribution page ID,
128 if (!empty($ids['contributionPage']) && !is_numeric($ids['contributionPage'])) {
129 // We don't need to worry if about removing contribution page id as it will be set later in
130 // CRM_Contribute_BAO_Contribution::loadRelatedObjects(..) using $objects['contribution']->contribution_page_id
131 unset($ids['contributionPage']);
134 if (!$this->loadObjects($input, $ids, $objects, $required, $paymentProcessorID)) {
141 * Load objects related to contribution.
145 * @input array information from Payment processor
147 * @param array $input
149 * @param array $objects
150 * @param bool $required
151 * @param int $paymentProcessorID
154 * @throws \CRM_Core_Exception
156 public function loadObjects($input, &$ids, &$objects, $required, $paymentProcessorID) {
157 CRM_Core_Error
::deprecatedFunctionWarning('use api methods in ipn');
158 $contribution = &$objects['contribution'];
159 $ids['paymentProcessor'] = $paymentProcessorID;
160 $success = $contribution->loadRelatedObjects($input, $ids);
161 $objects = array_merge($objects, $contribution->_relatedObjects
);
166 * Set contribution to failed.
168 * @param array $objects
170 * @deprecated use the api.
173 * @throws \CiviCRM_API3_Exception|\CRM_Core_Exception
175 public function failed($objects) {
176 CRM_Core_Error
::deprecatedFunctionWarning('use the api');
177 $contribution = &$objects['contribution'];
179 if (!empty($objects['membership'])) {
180 $memberships = &$objects['membership'];
181 if (is_numeric($memberships)) {
182 $memberships = [$objects['membership']];
186 $addLineItems = empty($contribution->id
);
187 $participant = &$objects['participant'];
188 $contribution->contribution_status_id
= CRM_Core_PseudoConstant
::getKey('CRM_Contribute_DAO_Contribution', 'contribution_status_id', 'Failed');
189 $contribution->save();
191 // Add line items for recurring payments.
192 if (!empty($objects['contributionRecur']) && $objects['contributionRecur']->id
&& $addLineItems) {
193 CRM_Contribute_BAO_ContributionRecur
::addRecurLineItems($objects['contributionRecur']->id
, $contribution);
196 if (!empty($memberships)) {
197 foreach ($memberships as $membership) {
198 // @fixme Should we cancel only Pending memberships? per cancelled()
199 $this->cancelMembership($membership, $membership->status_id
, FALSE);
204 $this->cancelParticipant($participant->id
);
207 Civi
::log()->debug("Setting contribution status to Failed");
212 * Handled pending contribution status.
216 * @param array $objects
217 * @param object $transaction
221 public function pending(&$objects, &$transaction) {
222 CRM_Core_Error
::deprecatedFunctionWarning('This function will be removed at some point');
223 $transaction->commit();
224 Civi
::log()->debug('Returning since contribution status is Pending');
225 echo 'Success: Returning since contribution status is pending<p>';
230 * Process cancelled payment outcome.
232 * @deprecated The intended replacement code is
234 * Contribution::update(FALSE)->setValues([
235 * 'cancel_date' => 'now',
236 * 'contribution_status_id:name' => 'Cancelled',
237 * ])->addWhere('id', '=', $contribution->id)->execute();
239 * @param array $objects
242 * @throws \CiviCRM_API3_Exception|\CRM_Core_Exception
244 public function cancelled($objects) {
245 CRM_Core_Error
::deprecatedFunctionWarning('Use Contribution create api to cancel the contribution');
246 $contribution = &$objects['contribution'];
248 if (empty($contribution->id
)) {
249 // This code is believed to be unreachable.
250 // this entire function is due to be deprecated in the near future so
251 // this code will live in a deprecated function until it gets removed.
252 $addLineItems = TRUE;
254 $contributionStatuses = CRM_Core_PseudoConstant
::get('CRM_Contribute_DAO_Contribution', 'contribution_status_id', [
255 'labelColumn' => 'name',
258 $contribution->contribution_status_id
= $contributionStatuses['Cancelled'];
259 $contribution->cancel_date
= self
::$_now;
260 $contribution->save();
261 // Add line items for recurring payments.
262 if (!empty($objects['contributionRecur']) && $objects['contributionRecur']->id
&& $addLineItems) {
263 CRM_Contribute_BAO_ContributionRecur
::addRecurLineItems($objects['contributionRecur']->id
, $contribution);
266 if (!empty($objects['membership'])) {
267 $memberships = &$objects['membership'];
268 if (is_numeric($memberships)) {
269 $memberships = [$objects['membership']];
272 if (!empty($memberships)) {
273 foreach ($memberships as $membership) {
275 $this->cancelMembership($membership, $membership->status_id
);
279 $participant = &$objects['participant'];
282 $this->cancelParticipant($participant->id
);
286 Contribution
::update(FALSE)->setValues([
287 'cancel_date' => 'now',
288 'contribution_status_id:name' => 'Cancelled',
289 ])->addWhere('id', '=', $contribution->id
)->execute();
292 Civi
::log()->debug("Setting contribution status to Cancelled");
297 * Rollback unhandled outcomes.
301 * @param array $objects
302 * @param CRM_Core_Transaction $transaction
306 public function unhandled(&$objects, &$transaction) {
307 CRM_Core_Error
::deprecatedFunctionWarning('This function will be removed at some point');
308 $transaction->rollback();
309 Civi
::log()->debug('Returning since contribution status is not handled');
310 echo 'Failure: contribution status is not handled<p>';
315 * Logic to cancel a participant record when the related contribution changes to failed/cancelled.
316 * @todo This is part of a bigger refactor for dev/core/issues/927 - "duplicate" functionality exists in CRM_Contribute_BAO_Contribution::cancel()
320 * @param $participantID
322 * @throws \CiviCRM_API3_Exception
324 private function cancelParticipant($participantID) {
325 // @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
326 $participantParams['id'] = $participantID;
327 $participantParams['status_id'] = 'Cancelled';
328 civicrm_api3('Participant', 'create', $participantParams);
332 * Logic to cancel a membership record when the related contribution changes to failed/cancelled.
333 * @todo This is part of a bigger refactor for dev/core/issues/927 - "duplicate" functionality exists in CRM_Contribute_BAO_Contribution::cancel()
334 * @param \CRM_Member_BAO_Membership $membership
335 * @param int $membershipStatusID
336 * @param bool $onlyCancelPendingMembership
337 * Do we only cancel pending memberships? OR memberships in any status? (see CRM-18688)
338 * @fixme Historically failed() cancelled membership in any status, cancelled() cancelled only pending memberships so we retain that behaviour for now.
341 private function cancelMembership($membership, $membershipStatusID, $onlyCancelPendingMembership = TRUE) {
342 CRM_Core_Error
::deprecatedFunctionWarning('use the api');
343 // @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
344 // Cancel only Pending memberships
345 $pendingMembershipStatusId = CRM_Core_PseudoConstant
::getKey('CRM_Member_BAO_Membership', 'status_id', 'Pending');
346 if (($membershipStatusID == $pendingMembershipStatusId) ||
($onlyCancelPendingMembership == FALSE)) {
347 $cancelledMembershipStatusId = CRM_Core_PseudoConstant
::getKey('CRM_Member_BAO_Membership', 'status_id', 'Cancelled');
349 $membership->status_id
= $cancelledMembershipStatusId;
352 $params = ['status_id' => $cancelledMembershipStatusId];
353 CRM_Member_BAO_Membership
::updateRelatedMemberships($membership->id
, $params);
355 // @todo Convert the above to API
356 // $membershipParams = [
357 // 'id' => $membership->id,
358 // 'status_id' => $cancelledMembershipStatusId,
360 // civicrm_api3('Membership', 'create', $membershipParams);
361 // CRM_Member_BAO_Membership::updateRelatedMemberships($membershipParams['id'], ['status_id' => $cancelledMembershipStatusId]);
369 * Jumbled up function.
371 * The purpose of this function is to transition a pending transaction to Completed including updating any
374 * It has been overloaded to also add recurring transactions to the database, cloning the original transaction and
375 * updating related entities.
377 * It is recommended to avoid calling this function directly and call the api functions:
378 * - contribution.completetransaction
379 * - contribution.repeattransaction
381 * These functions are the focus of testing efforts and more accurately reflect the division of roles
382 * (the job of the IPN class is to determine the outcome, transaction id, invoice id & to validate the source
383 * and from there it should be possible to pass off transaction management.)
385 * This function has been problematic for some time but there are now several tests via the api_v3_Contribution test
386 * and the Paypal & Authorize.net IPN tests so any refactoring should be done in conjunction with those.
388 * This function needs to have the 'body' moved to the CRM_Contribute_BAO_Contribute class and to undergo
389 * refactoring to separate the complete transaction and repeat transaction functionality into separate functions with
390 * a shared function that updates related components.
392 * Note that it is not necessary payment processor extension to implement an IPN class now. In general the code on the
393 * IPN class is better accessed through the api which de-jumbles it a bit.
395 * e.g the payment class can have a function like (based on Omnipay extension):
397 * public function handlePaymentNotification() {
398 * $response = $this->getValidatedOutcome();
399 * if ($response->isSuccessful()) {
401 * // @todo check if it is a repeat transaction & call repeattransaction instead.
402 * civicrm_api3('contribution', 'completetransaction', array('id' => $this->transaction_id));
404 * catch (CiviCRM_API3_Exception $e) {
405 * if (!stristr($e->getMessage(), 'Contribution already completed')) {
406 * $this->handleError('error', $this->transaction_id . $e->getMessage(), 'ipn_completion', 9000, 'An error may
407 * have occurred. Please check your receipt is correct');
408 * $this->redirectOrExit('success');
410 * elseif ($this->transaction_id) {
411 * civicrm_api3('contribution', 'create', array('id' => $this->transaction_id, 'contribution_status_id' =>
415 * @param array $input
417 * @param array $objects
419 * @throws \CRM_Core_Exception
420 * @throws \CiviCRM_API3_Exception
422 public function completeTransaction($input, $ids, $objects) {
423 CRM_Core_Error
::deprecatedFunctionWarning('Use Payment.create api');
424 CRM_Contribute_BAO_Contribution
::completeOrder($input, !empty($objects['contributionRecur']) ?
$objects['contributionRecur']->id
: NULL, $objects['contribution']->id ??
NULL);
429 * Get site billing ID.
435 public function getBillingID(&$ids) {
436 CRM_Core_Error
::deprecatedFunctionWarning('CRM_Core_BAO_LocationType::getBilling()');
437 $ids['billing'] = CRM_Core_BAO_LocationType
::getBilling();
438 if (!$ids['billing']) {
439 CRM_Core_Error
::debug_log_message(ts('Please set a location type of %1', [1 => 'Billing']));
440 echo "Failure: Could not find billing location type<p>";
449 * @todo confirm this function is not being used by any payment processor outside core & remove.
451 * Note that the compose message part has been moved to contribution
452 * In general LoadObjects is called first to get the objects but the composeMessageArray function now calls it
454 * @param array $input
455 * Incoming data from Payment processor.
457 * Related object IDs.
458 * @param array $objects
460 * @throws \CiviCRM_API3_Exception
462 public function sendMail($input, $ids, $objects) {
463 CRM_Core_Error
::deprecatedFunctionWarning('this should be done via completetransaction api');
464 civicrm_api3('Contribution', 'sendconfirmation', [
465 'id' => $objects['contribution']->id
,