[ACL-135] Add support for attempt_failed payment status (#57)

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2024-07-18
+
+### Added
+
+- Support for `attempt_failed` payment status
+
 ## [2.2.0] - 2024-07-15
 
 ### Added

README.md

@@ -25,8 +25,9 @@
         4. [Executed Status](#status-executed)
         5. [Settled Status](#status-settled)
         6. [Failed Status](#status-failed)
-        7. [Authorization flow config](#auth-flow-config)
-        8. [Source of funds](#source-of-funds)
+        7. [Attempt Failed Status](#status-attempt-failed)
+        8. [Authorization flow config](#auth-flow-config)
+        9. [Source of funds](#source-of-funds)
 7. [Authorizing a payment](#authorizing-payment)
 8. [Refunds](#refunds)
 9. [Payouts](#payouts)
@@ -418,7 +419,8 @@ $payment->isAuthorizing();
 $payment->isAuthorized(); // Will also return false when the payment has progressed to executed, failed or settled states.
 $payment->isExecuted(); // Will also return false when the payment has progressed to failed or settled states.
 $payment->isSettled(); 
-$payment->isFailed();
+$payment->isFailed(); // Payment has failed
+$payment->isAttemptFailed(); // Payment attempt has failed, only available if payment retries are enabled.
 ```
 
 Or you can get the status as a string and compare it to the provided constants in `PaymentStatus`:
@@ -587,6 +589,23 @@ if ($payment instanceof PaymentFailedInterface) {
 }
 ```
 
+<a name="status-attempt-failed"></a>
+
+### Attempt Failed Status
+
+> Status only available when you enable payment retries.
+
+```php
+use TrueLayer\Interfaces\Payment\PaymentAttemptFailedInterface;
+
+if ($payment instanceof PaymentAttemptFailedInterface) {
+    $payment->getFailedAt(); // The date and time the payment failed at
+    $payment->getFailureStage(); // The status the payment was when it failed, one of `authorization_required`, `authorizing` or `authorized`
+    $payment->getFailureReason(); // The reason the payment failed. Handle unexpected values gracefully as an unknown failure.
+    $payment->getAuthorizationFlowConfig(); // see authorization flow config
+}
+```
+
 <a name="auth-flow-config"></a>
 
 ### Authorization flow config

config/bindings.php

@@ -23,11 +23,13 @@
     Interfaces\Payment\PaymentExecutedInterface::class => Entities\Payment\PaymentRetrieved\PaymentExecuted::class,
     Interfaces\Payment\PaymentSettledInterface::class => Entities\Payment\PaymentRetrieved\PaymentSettled::class,
     Interfaces\Payment\PaymentFailedInterface::class => Entities\Payment\PaymentRetrieved\PaymentFailed::class,
+    Interfaces\Payment\PaymentAttemptFailedInterface::class => Entities\Payment\PaymentRetrieved\PaymentAttemptFailed::class,
     Interfaces\Payment\PaymentSourceInterface::class => Entities\Payment\PaymentRetrieved\PaymentSource::class,
 
     TrueLayer\Interfaces\Payment\StartAuthorizationFlowRequestInterface::class => Entities\Payment\AuthorizationFlow\StartAuthorizationFlowRequest::class,
     Interfaces\Payment\AuthorizationFlow\AuthorizationFlowInterface::class => Entities\Payment\AuthorizationFlow\AuthorizationFlow::class,
     Interfaces\Payment\AuthorizationFlow\ConfigurationInterface::class => Entities\Payment\AuthorizationFlow\Configuration::class,
+    Interfaces\Payment\AuthorizationFlow\ActionInterface::class => Entities\Payment\AuthorizationFlow\Action::class,
     Interfaces\Payment\AuthorizationFlow\Action\ProviderSelectionActionInterface::class => Entities\Payment\AuthorizationFlow\Action\ProviderSelectionAction::class,
     Interfaces\Payment\AuthorizationFlow\Action\RedirectActionInterface::class => Entities\Payment\AuthorizationFlow\Action\RedirectAction::class,
     Interfaces\Payment\AuthorizationFlow\Action\WaitActionInterface::class => Entities\Payment\AuthorizationFlow\Action\WaitAction::class,

config/discriminations.php

@@ -23,6 +23,7 @@
         PaymentStatus::EXECUTED => Interfaces\Payment\PaymentExecutedInterface::class,
         PaymentStatus::SETTLED => Interfaces\Payment\PaymentSettledInterface::class,
         PaymentStatus::FAILED => Interfaces\Payment\PaymentFailedInterface::class,
+        PaymentStatus::ATTEMPT_FAILED => Interfaces\Payment\PaymentAttemptFailedInterface::class,
     ],
     Interfaces\Payment\AuthorizationFlow\AuthorizationFlowResponseInterface::class => [
         'discriminate_on' => 'status',

src/Constants/AuthorizationFlowActionTypes.php

@@ -9,4 +9,5 @@ class AuthorizationFlowActionTypes
     public const PROVIDER_SELECTION = 'provider_selection';
     public const REDIRECT = 'redirect';
     public const WAIT = 'wait';
+    public const RETRY = 'retry';
 }

src/Constants/PaymentStatus.php

@@ -11,5 +11,6 @@ class PaymentStatus
     public const AUTHORIZED = 'authorized';
     public const EXECUTED = 'executed';
     public const FAILED = 'failed';
+    public const ATTEMPT_FAILED = 'attempt_failed';
     public const SETTLED = 'settled';
 }

src/Entities/Payment/AuthorizationFlow/Action.php

@@ -5,12 +5,27 @@
 namespace TrueLayer\Entities\Payment\AuthorizationFlow;
 
 use TrueLayer\Entities\Entity;
-use TrueLayer\Interfaces\Payment\AuthorizationFlow\ActionInterface;
+use TrueLayer\Interfaces\Payment\AuthorizationFlow\Action\ActionInterface;
 
-abstract class Action extends Entity implements ActionInterface
+class Action extends Entity implements ActionInterface
 {
+    /**
+     * @var string
+     */
+    protected string $type;
+
+    /**
+     * @var string[]
+     */
+    protected array $arrayFields = [
+        'type',
+    ];
+
     /**
      * @return string
      */
-    abstract public function getType(): string;
+    public function getType(): string
+    {
+        return $this->type;
+    }
 }

src/Entities/Payment/AuthorizationFlow/Action/ProviderSelectionAction.php

@@ -4,7 +4,6 @@
 
 namespace TrueLayer\Entities\Payment\AuthorizationFlow\Action;
 
-use TrueLayer\Constants\AuthorizationFlowActionTypes;
 use TrueLayer\Entities\Payment\AuthorizationFlow\Action;
 use TrueLayer\Interfaces\Payment\AuthorizationFlow\Action\ProviderSelectionActionInterface;
 use TrueLayer\Interfaces\Provider\ProviderInterface;
@@ -38,12 +37,4 @@ public function getProviders(): array
     {
         return $this->providers;
     }
-
-    /**
-     * @return string
-     */
-    public function getType(): string
-    {
-        return AuthorizationFlowActionTypes::PROVIDER_SELECTION;
-    }
 }

src/Entities/Payment/AuthorizationFlow/Action/RedirectAction.php

@@ -4,7 +4,6 @@
 
 namespace TrueLayer\Entities\Payment\AuthorizationFlow\Action;
 
-use TrueLayer\Constants\AuthorizationFlowActionTypes;
 use TrueLayer\Entities\Payment\AuthorizationFlow\Action;
 use TrueLayer\Interfaces\Payment\AuthorizationFlow\Action\RedirectActionInterface;
 use TrueLayer\Interfaces\Provider\ProviderInterface;
@@ -45,14 +44,6 @@ public function getUri(): string
         return $this->uri;
     }
 
-    /**
-     * @return string
-     */
-    public function getType(): string
-    {
-        return AuthorizationFlowActionTypes::REDIRECT;
-    }
-
     /**
      * @return string
      */

src/Entities/Payment/AuthorizationFlow/Action/WaitAction.php

@@ -4,24 +4,10 @@
 
 namespace TrueLayer\Entities\Payment\AuthorizationFlow\Action;
 
-use TrueLayer\Constants\AuthorizationFlowActionTypes;
 use TrueLayer\Entities\Payment\AuthorizationFlow\Action;
 use TrueLayer\Interfaces\Payment\AuthorizationFlow\Action\WaitActionInterface;
 
 class WaitAction extends Action implements WaitActionInterface
 {
-    /**
-     * @var string[]
-     */
-    protected array $arrayFields = [
-        'type',
-    ];
 
-    /**
-     * @return string
-     */
-    public function getType(): string
-    {
-        return AuthorizationFlowActionTypes::WAIT;
-    }
 }

src/Entities/Payment/PaymentRetrieved.php

@@ -177,6 +177,14 @@ public function isFailed(): bool
         return $this->getStatus() === PaymentStatus::FAILED;
     }
 
+    /**
+     * @return bool
+     */
+    public function isAttemptFailed(): bool
+    {
+        return $this->getStatus() === PaymentStatus::ATTEMPT_FAILED;
+    }
+
     /**
      * @return bool
      */

src/Entities/Payment/PaymentRetrieved/PaymentAttemptFailed.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TrueLayer\Entities\Payment\PaymentRetrieved;
+
+use TrueLayer\Interfaces\Payment\PaymentAttemptFailedInterface;
+
+final class PaymentAttemptFailed extends PaymentFailure implements PaymentAttemptFailedInterface
+{
+}

src/Entities/Payment/PaymentRetrieved/PaymentFailed.php

@@ -6,66 +6,6 @@
 
 use TrueLayer\Interfaces\Payment\PaymentFailedInterface;
 
-final class PaymentFailed extends _PaymentWithAuthorizationConfig implements PaymentFailedInterface
+final class PaymentFailed extends PaymentFailure implements PaymentFailedInterface
 {
-    /**
-     * @var \DateTimeInterface
-     */
-    protected \DateTimeInterface $failedAt;
-
-    /**
-     * @var string
-     */
-    protected string $failureStage;
-
-    /**
-     * @var string
-     */
-    protected string $failureReason;
-
-    /**
-     * @return mixed[]
-     */
-    protected function casts(): array
-    {
-        return \array_merge_recursive(parent::casts(), [
-            'failed_at' => \DateTimeInterface::class,
-        ]);
-    }
-
-    /**
-     * @return mixed[]
-     */
-    protected function arrayFields(): array
-    {
-        return \array_merge(parent::arrayFields(), [
-            'failed_at',
-            'failure_stage',
-            'failure_reason',
-        ]);
-    }
-
-    /**
-     * @return \DateTimeInterface
-     */
-    public function getFailedAt(): \DateTimeInterface
-    {
-        return $this->failedAt;
-    }
-
-    /**
-     * @return string
-     */
-    public function getFailureStage(): string
-    {
-        return $this->failureStage;
-    }
-
-    /**
-     * @return string|null
-     */
-    public function getFailureReason(): ?string
-    {
-        return $this->failureReason ?? null;
-    }
 }

src/Entities/Payment/PaymentRetrieved/PaymentFailure.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TrueLayer\Entities\Payment\PaymentRetrieved;
+
+abstract class PaymentFailure extends _PaymentWithAuthorizationConfig
+{
+    /**
+     * @var \DateTimeInterface
+     */
+    protected \DateTimeInterface $failedAt;
+
+    /**
+     * @var string
+     */
+    protected string $failureStage;
+
+    /**
+     * @var string
+     */
+    protected string $failureReason;
+
+    /**
+     * @return mixed[]
+     */
+    protected function casts(): array
+    {
+        return \array_merge_recursive(parent::casts(), [
+            'failed_at' => \DateTimeInterface::class,
+        ]);
+    }
+
+    /**
+     * @return mixed[]
+     */
+    protected function arrayFields(): array
+    {
+        return \array_merge(parent::arrayFields(), [
+            'failed_at',
+            'failure_stage',
+            'failure_reason',
+        ]);
+    }
+
+    /**
+     * @return \DateTimeInterface
+     */
+    public function getFailedAt(): \DateTimeInterface
+    {
+        return $this->failedAt;
+    }
+
+    /**
+     * @return string
+     */
+    public function getFailureStage(): string
+    {
+        return $this->failureStage;
+    }
+
+    /**
+     * @return string|null
+     */
+    public function getFailureReason(): ?string
+    {
+        return $this->failureReason ?? null;
+    }
+}

src/Interfaces/Payment/AuthorizationFlow/Action/ActionInterface.php

@@ -4,12 +4,7 @@
 
 namespace TrueLayer\Interfaces\Payment\AuthorizationFlow\Action;
 
-use TrueLayer\Interfaces\ArrayableInterface;
-
-interface ActionInterface extends ArrayableInterface
+interface ActionInterface extends \TrueLayer\Interfaces\Payment\AuthorizationFlow\ActionInterface
 {
-    /**
-     * @return string
-     */
-    public function getType(): string;
+
 }

src/Interfaces/Payment/AuthorizationFlow/ActionInterface.php

@@ -8,4 +8,8 @@
 
 interface ActionInterface extends ArrayableInterface
 {
+    /**
+     * @return string
+     */
+    public function getType(): string;
 }

src/Interfaces/Payment/PaymentAttemptFailedInterface.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TrueLayer\Interfaces\Payment;
+
+interface PaymentAttemptFailedInterface extends PaymentFailureInterface
+{
+}