Add supportsRefund/doRefund for gateways whose Omnipay driver implements refund()

Implements CiviCRM's refund contract (PaymentProcessor.refund API /
supportsRefund capability) generically: supportsRefund() resolves the
Omnipay gateway class without instantiating it and reports TRUE only when
that class exposes a refund() method. doRefund() sends the refund via the
gateway (transactionReference = original trxn_id) and returns
refund_trxn_id / refund_status per the core contract. Failures throw
PaymentProcessorException so CiviCRM never records a refund the gateway
rejected. Currency defaults to the original transaction's currency.

Tested against Mollie (iDeal/Bancontact) on CiviCRM 6.x.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Richard van Oosterhout

CRM/Core/Payment/OmnipayMultiProcessor.php

@@ -271,6 +271,85 @@ public function doPayment(&$params, $component = 'contribute'): array {
     }
   }
 
+  /**
+   * Does this processor support refunds?
+   *
+   * Generic for any Omnipay gateway that exposes a refund() method
+   * (the tested target is Mollie). The gateway class is resolved without
+   * instantiating it, so this is safe to call in listing contexts.
+   *
+   * @return bool
+   */
+  public function supportsRefund() {
+    try {
+      $this->ensurePaymentProcessorTypeIsSet();
+      $shortName = str_replace('omnipay_', '', $this->_paymentProcessor['payment_processor_type']);
+      $gatewayClass = \Omnipay\Common\Helper::getGatewayClassName($shortName);
+      return class_exists($gatewayClass) && method_exists($gatewayClass, 'refund');
+    }
+    catch (\Exception $e) {
+      return FALSE;
+    }
+  }
+
+  /**
+   * Submit a refund to the payment processor.
+   *
+   * Generic for any Omnipay gateway that exposes a refund() method; the
+   * tested target is Mollie. On failure an exception is thrown (rather than
+   * returning a failure array) so that CiviCRM never records a refund that
+   * the gateway rejected.
+   *
+   * @param array $params
+   *   Expected keys: trxn_id (the gateway's original transaction reference),
+   *   amount, and optionally currency (resolved from the original financial
+   *   transaction when omitted).
+   *
+   * @return array
+   *   refund_trxn_id, refund_status ('Completed'), fee_amount, trxn_date.
+   *
+   * @throws \Civi\Payment\Exception\PaymentProcessorException
+   */
+  public function doRefund(&$params) {
+    if (empty($params['trxn_id']) || empty($params['amount'])) {
+      throw new \Civi\Payment\Exception\PaymentProcessorException('doRefund requires trxn_id and amount');
+    }
+    $currency = $params['currency'] ?? NULL;
+    if (empty($currency)) {
+      // Look up the currency of the original transaction so the refund is
+      // issued in the same currency; fall back to the default currency.
+      $currency = CRM_Core_DAO::singleValueQuery(
+        'SELECT currency FROM civicrm_financial_trxn WHERE trxn_id = %1',
+        [1 => [$params['trxn_id'], 'String']]
+      ) ?: $this->getCurrency($params);
+    }
+    $this->ensurePaymentProcessorTypeIsSet();
+    $this->createGatewayObject();
+    $this->setProcessorFields();
+
+    try {
+      $response = $this->gateway->refund([
+        'transactionReference' => $params['trxn_id'],
+        'amount' => \Civi::format()->machineMoney($params['amount'], $currency),
+        'currency' => $currency,
+      ])->send();
+    }
+    catch (\Exception $e) {
+      throw new \Civi\Payment\Exception\PaymentProcessorException('Refund failed: ' . $e->getMessage());
+    }
+    if (!$response->isSuccessful()) {
+      throw new \Civi\Payment\Exception\PaymentProcessorException('Refund failed: ' . $response->getMessage());
+    }
+    return [
+      // For Mollie getTransactionId() is the new refund id (re_...) while
+      // getTransactionReference() remains the original payment id (tr_...).
+      'refund_trxn_id' => $response->getTransactionId(),
+      'refund_status' => 'Completed',
+      'fee_amount' => 0,
+      'trxn_date' => date('YmdHis'),
+    ];
+  }
+
   /**
    * Initialize class variables.
    *