Added the transactionHandler() method to the Payment gateway interface

- Added experimental Transaction-related interfaces

Changelog.md

@@ -129,6 +129,7 @@
  - `getRemoteId()`
  - `isOffline()`
 - BC: Added the `getTransactionAmount()` method to the `PaymentResponse` interface
+- BC: Added the `transactionHandler()` method to the `PaymentGateway` interface (**experimental** feature)
 - BC: Added the following methods to the `Payable` interface:
  - `getNumber()`
  - `getPayableRemoteId()`
@@ -146,6 +147,8 @@
  - `getShippingCountries()`
 - 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
 - Added the `Schematized` interface
 - Added the nette/schema package requirement (v1.2.5+)
 - Fixed possible null return type on Billpayer::getName() when is_organization is true but the company name is null

src/Payment/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
 

src/Payment/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;
+}

src/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;
 }

src/Payment/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();
 }

src/Payment/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;
+}

src/Payment/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;
+}

src/Payment/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();
+}

src/Payment/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;

src/Payment/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;

src/Payment/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;