Added the transactionHandler() method to the Payment gateway interface

- Added experimental Transaction-related interfaces

Changelog.md

@@ -19,9 +19,12 @@
     - `getRemoteId()`
     - `isOffline()`
 - BC: Added the `getTransactionAmount()` method to the `PaymentResponse` interface
+- BC: Added the `transactionHandler()` method to the `PaymentGateway` interface (experimental feature)
 - BC: Changed the `PaymentMethod` interface into Configurable
 - Deprecated the `PaymentMethod::getConfiguration()` in favor of `configuration()`
 - Deprecated the `PaymentResponse::getAmountPaid()` method in favor of `getTransactionAmount()`
+- Added a series of **experimental** transaction-style interfaces. They shouldn't be used yet, but
+  have been added so that they can be implemented during the v4.x lifecycle without breaking existing implementations 
 
 ## 3.x Series
 

Contracts/PaymentAware.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Contains the PaymentAware interface.
+ *
+ * @copyright   Copyright (c) 2024 Vanilo UG
+ * @author      Attila Fulop
+ * @license     MIT
+ * @since       2024-04-24
+ *
+ */
+
+namespace Vanilo\Payment\Contracts;
+
+/**
+ * @experimental
+ */
+interface PaymentAware
+{
+    public function getPaymentId(): string;
+
+    public function getPayment(): Payment;
+}

Contracts/PaymentGateway.php

@@ -29,5 +29,8 @@ public function createPaymentRequest(
 
     public function processPaymentResponse(Request $request, array $options = []): PaymentResponse;
 
+    /** @experimental  */
+    public function transactionHandler(): ?TransactionHandler;
+
     public function isOffline(): bool;
 }

Contracts/PaymentStatus.php

@@ -14,6 +14,8 @@
 
 namespace Vanilo\Payment\Contracts;
 
+use Konekt\Enum\EnumInterface;
+
 /**
  * @method static PaymentStatus PENDING()
  * @method static PaymentStatus AUTHORIZED()
@@ -36,11 +38,6 @@
  * @method bool isRefunded()
  * @method bool isPartiallyRefunded()
  */
-interface PaymentStatus
+interface PaymentStatus extends EnumInterface
 {
-    /** @return string */
-    public function value();
-
-    /** @return string */
-    public function label();
 }

Contracts/Transaction.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Contains the Transaction interface.
+ *
+ * @copyright   Copyright (c) 2024 Vanilo UG
+ * @author      Attila Fulop
+ * @license     MIT
+ * @since       2024-04-24
+ *
+ */
+
+namespace Vanilo\Payment\Contracts;
+
+use StringBackedEnum;
+
+/**
+ * @experimental is subject to change. don't use it yet!
+ */
+interface Transaction extends PaymentAware
+{
+    public function wasSuccessful(): bool;
+
+    public function message(): string;
+
+    public function attemptedAmount(): float;
+
+    public function transactedAmount(): float;
+
+    public function isCharge(): bool;
+
+    public function isCredit(): bool;
+
+    public function getTransactionId(): ?string;
+
+    public function getRemoteSubjectId(): ?string;
+
+    public function getRemoteSubjectType(): ?string;
+
+    public function getNativeStatus(): StringBackedEnum;
+}

Contracts/TransactionHandler.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Contains the TransactionHandler interface.
+ *
+ * @copyright   Copyright (c) 2024 Vanilo UG
+ * @author      Attila Fulop
+ * @license     MIT
+ * @since       2024-04-24
+ *
+ */
+
+namespace Vanilo\Payment\Contracts;
+
+/**
+ * @experimental don't use it yet, don't rely on it yet!
+ */
+interface TransactionHandler
+{
+    public function supportsRefunds(): bool;
+
+    public function issueRefund(Payment $payment, float $amount, array $options = []): Transaction|TransactionNotCreated;
+}

Contracts/TransactionNotCreated.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Contains the FailedOperation interface.
+ *
+ * @copyright   Copyright (c) 2024 Vanilo UG
+ * @author      Attila Fulop
+ * @license     MIT
+ * @since       2024-04-24
+ *
+ */
+
+namespace Vanilo\Payment\Contracts;
+
+/**
+ * @experimental
+ */
+interface TransactionNotCreated extends PaymentAware
+{
+    public function reason(): ?string;
+
+    public function shouldBeRetried(): bool;
+
+    public function getDetails();
+}

Gateways/NullGateway.php

@@ -20,6 +20,7 @@
 use Vanilo\Payment\Contracts\PaymentGateway;
 use Vanilo\Payment\Contracts\PaymentRequest;
 use Vanilo\Payment\Contracts\PaymentResponse;
+use Vanilo\Payment\Contracts\TransactionHandler;
 use Vanilo\Payment\Requests\NullRequest;
 use Vanilo\Payment\Responses\NullResponse;
 
@@ -43,6 +44,11 @@ public function processPaymentResponse(Request $request, array $options = []): P
         return new NullResponse();
     }
 
+    public function transactionHandler(): ?TransactionHandler
+    {
+        return null;
+    }
+
     public function isOffline(): bool
     {
         return true;

Tests/Examples/PlasticPayments.php

@@ -20,6 +20,7 @@
 use Vanilo\Payment\Contracts\PaymentGateway;
 use Vanilo\Payment\Contracts\PaymentRequest;
 use Vanilo\Payment\Contracts\PaymentResponse;
+use Vanilo\Payment\Contracts\TransactionHandler;
 use Vanilo\Payment\Requests\NullRequest;
 use Vanilo\Payment\Responses\NullResponse;
 
@@ -43,6 +44,11 @@ public function processPaymentResponse(Request $request, array $options = []): P
         return new NullResponse();
     }
 
+    public function transactionHandler(): ?TransactionHandler
+    {
+        return null;
+    }
+
     public function isOffline(): bool
     {
         return false;

Tests/Examples/UnorthodoxGateway.php

@@ -20,6 +20,7 @@
 use Vanilo\Payment\Contracts\PaymentGateway;
 use Vanilo\Payment\Contracts\PaymentRequest;
 use Vanilo\Payment\Contracts\PaymentResponse;
+use Vanilo\Payment\Contracts\TransactionHandler;
 use Vanilo\Payment\Models\PaymentStatus;
 use Vanilo\Payment\Requests\NullRequest;
 
@@ -51,6 +52,11 @@ public function processPaymentResponse(Request|UnorthodoxPaymentResponse $reques
         );
     }
 
+    public function transactionHandler(): ?TransactionHandler
+    {
+        return null;
+    }
+
     public function isOffline(): bool
     {
         return false;