Improve updateContributionRefund() function to handle new field and use API.

CRM/Core/Payment/MJWIPNTrait.php

@@ -94,24 +94,66 @@ trait CRM_Core_Payment_MJWIPNTrait {
   }
 
   /**
-   * Record a refunded contribution
-   * This function ONLY supports full refunds
+   * Record a refund on a contribution
+   * This wraps around the payment.create API to support earlier releases than features were available
+   *
+   * Examples:
+   * $result = civicrm_api3('Payment', 'create', [
+   *   'contribution_id' => 590,
+   *   'total_amount' => -3,
+   *   'trxn_date' => 20191105200300,
+   *   'trxn_result_code' => "Test a refund with fees",
+   *   'fee_amount' => -0.25,
+   *   'trxn_id' => "abctx123",
+   *   'order_reference' => "abcor123",
+   * ]);
+   *
+   *  Returns:
+   * "is_error": 0,
+   * "version": 3,
+   * "count": 1,
+   * "id": 465,
+   * "values": {
+   *   "465": {
+   *     "id": "465",
+   *     "from_financial_account_id": "7",
+   *     "to_financial_account_id": "6",
+   *     "trxn_date": "20191105200300",
+   *     "total_amount": "-3",
+   *     "fee_amount": "-0.25",
+   *     "net_amount": "",
+   *     "currency": "USD",
+   *     "is_payment": "1",
+   *     "trxn_id": "abctx123",
+   *     "trxn_result_code": "Test a refund with fees",
+   *     "status_id": "7",
+   *     "payment_processor_id": ""
+   *   }
+   * }
    *
    * @param array $params
    *
    * @throws \CiviCRM_API3_Exception
    */
   protected function updateContributionRefund($params) {
-    $this->checkRequiredParams('updateContributionRefund', ['id', 'payment_trxn_id'], $params);
-
-    if (empty($params['cancel_date'])) {
-      $params['cancel_date'] = date('YmdHis');
-    }
-    $params['contribution_status_id'] = CRM_Core_PseudoConstant::getKey('CRM_Contribute_BAO_Contribution', 'contribution_status_id', 'Refunded');
+    $this->checkRequiredParams('updateContributionRefund', ['contribution_id', 'total_amount'], $params);
 
-    civicrm_api3('Contribution', 'create', $params);
+    $financialTrxn = civicrm_api3('Payment', 'create', $params);
 
-    $this->updatePaymentTrxnID($params['id'], $params['payment_trxn_id']);
+    // order_reference field was introduced in 5.20 but support was not available to save it via Payment.Create
+    if (version_compare(\CRM_Utils_System::version(), '5.20', '<')) {
+      // Order reference field not available so we do nothing with it.
+    }
+    else {
+      // @fixme We are on 5.20 or above, so have order_reference field available. But it's not yet updated by Payment.Create API
+      if (!empty($params['order_reference'])) {
+        civicrm_api3('FinancialTrxn', 'create', [
+          'id' => $financialTrxn['id'],
+          'trxn_id' => $params['trxn_id'],
+          'order_reference' => $params['order_reference'] ?? '',
+        ]);
+      }
+    }
   }
 
   /**
@@ -245,10 +287,11 @@ trait CRM_Core_Payment_MJWIPNTrait {
    * Update the payment record so the trxn_id matches the actual transaction from the payment processor as we may have multiple transactions for a single payment (eg. failures, then success).
    * @param int $contributionID
    * @param string $trxnID
+   * @param string $orderReference
    *
    * @throws \CiviCRM_API3_Exception
    */
-  private function updatePaymentTrxnID($contributionID, $trxnID) {
+  private function updatePaymentTrxnID($contributionID, $trxnID, $orderReference = '') {
     // @fixme: There needs to be a better way to do this!!
     //   Contribution trxn_id = invoice_id, payment trxn_id = charge_id
     //   but calling completetransaction does not allow us to do that.
@@ -264,6 +307,7 @@ trait CRM_Core_Payment_MJWIPNTrait {
     civicrm_api3('FinancialTrxn', 'create', [
       'id' => $paymentID,
       'trxn_id' => $trxnID,
+      'order_reference' => $orderReference,
     ]);
   }
 

docs/release/release_notes.md

@@ -8,6 +8,10 @@ Where:
 * minor: Breaking change in some circumstances, or a new feature. Read carefully and make sure you understand the impact of the change.
 * incremental: A "safe" change / improvement. Should *always* be safe to upgrade.
 
+## Release 0.6
+
+* Improve updateContributionRefund() function to handle new `order_reference` field and use `Payment.create` API.
+
 ## Release 0.5.1
 
 * Fix getBillingEmail() to work in more circumstances and add tests

info.xml

@@ -13,9 +13,9 @@
     <url desc="Support">https://www.mjwconsult.co.uk</url>
     <url desc="Licensing">http://www.gnu.org/licenses/agpl-3.0.html</url>
   </urls>
-  <releaseDate>2019-11-01</releaseDate>
-  <version>0.5.1</version>
-  <develStage>stable</develStage>
+  <releaseDate>2019-11-14</releaseDate>
+  <version>0.6.beta1</version>
+  <develStage>beta</develStage>
   <compatibility>
     <ver>5.13</ver>
   </compatibility>