Added build gateway request event

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release Notes for Omnipay integration package for Craft Commerce
 
+## Unreleased
+
+- It’s now possible to modify gateway requests before they are sent.
+- Added `craft\commerce\omnipay\base\Gateway::EVENT_BUILD_GATEWAY_REQUEST`.
+- Added `craft\commerce\omnipay\events\BuildGatewayRequestEvent`.
+
 ## 4.1.0 - 2024-03-14
 
 - Added Craft CMS 5 and Craft Commerce 5 compatibility.

src/base/Gateway.php

@@ -14,6 +14,7 @@
 use craft\commerce\models\payments\CreditCardPaymentForm;
 use craft\commerce\models\PaymentSource;
 use craft\commerce\models\Transaction;
+use craft\commerce\omnipay\events\BuildGatewayRequestEvent;
 use craft\commerce\omnipay\events\GatewayRequestEvent;
 use craft\commerce\omnipay\events\ItemBagEvent;
 use craft\commerce\omnipay\events\SendPaymentRequestEvent;
@@ -105,6 +106,29 @@ abstract class Gateway extends BaseGateway
      */
     public const EVENT_BEFORE_SEND_PAYMENT_REQUEST = 'beforeSendPaymentRequest';
 
+    /**
+     * @event BuildGatewayRequestEvent The event that is triggered when a gateway request is being built.
+     * @since 4.2.0
+     *
+     * Plugins get a chance to provide additional data to any request that is made in the context of paying for an order.
+     *
+     * There are some restrictions:
+     *     Changes to the `Transaction` model available as the `transaction` property will be ignored;
+     *
+     * ```php
+     * use craft\commerce\omnipay\base\Gateway;
+     * use craft\commerce\omnipay\events\BuildGatewayRequestEvent;
+     * use yii\base\Event;
+     *
+     * Event::on(Gateway::class, Gateway::EVENT_BUILD_GATEWAY_REQUEST, function(BuildGatewayRequestEvent $e) {
+     *     if ($e->transaction->type === 'purchase') {
+     *         $e->request['someKey'] = 'some value';
+     *     }
+     * });
+     * ```
+     */
+    public const EVENT_BUILD_GATEWAY_REQUEST = 'buildGatewayRequest';
+
     /**
      * @var bool|string Whether cart information should be sent to the payment gateway
      */
@@ -611,7 +635,15 @@ protected function createRequest(Transaction $transaction, ?BasePaymentForm $for
             $this->populateRequest($request, $form);
         }
 
-        return $request;
+        $event = new BuildGatewayRequestEvent([
+            'transaction' => $transaction,
+            'request' => $request,
+            'type' => $transaction->type,
+        ]);
+
+        $this->trigger(self::EVENT_BUILD_GATEWAY_REQUEST, $event);
+
+        return $event->request;
     }
 
     /**

src/events/BuildGatewayRequestEvent.php

@@ -0,0 +1,35 @@
+<?php
+/**
+ * @link https://craftcms.com/
+ * @copyright Copyright (c) Pixel & Tonic, Inc.
+ * @license MIT
+ */
+
+namespace craft\commerce\omnipay\events;
+
+use craft\commerce\models\Transaction;
+use yii\base\Event;
+
+/**
+ * Class BuildGatewayRequestEvent
+ *
+ * @author Pixel & Tonic, Inc. <support@pixelandtonic.com>
+ * @since 4.2.0
+ */
+class BuildGatewayRequestEvent extends Event
+{
+    /**
+     * @var Transaction The transaction being used as the base for request
+     */
+    public Transaction $transaction;
+
+    /**
+     * @var array The request being used
+     */
+    public array $request;
+
+    /**
+     * @var string|null The type of request being made
+     */
+    public ?string $type = null;
+}

src/events/GatewayRequestEvent.php

@@ -1,4 +1,9 @@
 <?php
+/**
+ * @link https://craftcms.com/
+ * @copyright Copyright (c) Pixel & Tonic, Inc.
+ * @license MIT
+ */
 
 namespace craft\commerce\omnipay\events;