Improve docblocks for better IDE experience

src/Interfaces/Payment/PaymentAttemptFailedInterface.php

@@ -4,6 +4,10 @@
 
 namespace TrueLayer\Interfaces\Payment;
 
+/**
+ * A failed payment attempt - it was authorized successfully, but the money did not move. Only reachable
+ * when payment retries are enabled; the payment may still succeed on a later attempt.
+ */
 interface PaymentAttemptFailedInterface extends PaymentFailureInterface
 {
 }

src/Interfaces/Payment/PaymentAuthorizationRequiredInterface.php

@@ -4,6 +4,10 @@
 
 namespace TrueLayer\Interfaces\Payment;
 
+/**
+ * A payment yet to be authorized. This is the first status for a payment that requires further actions to
+ * be authorized.
+ */
 interface PaymentAuthorizationRequiredInterface extends PaymentRetrievedInterface
 {
 }

src/Interfaces/Payment/PaymentAuthorizedInterface.php

@@ -6,14 +6,22 @@
 
 use TrueLayer\Interfaces\Payment\AuthorizationFlow\ConfigurationInterface;
 
+/**
+ * An authorized payment - no more actions required, waiting for outcome.
+ */
 interface PaymentAuthorizedInterface extends PaymentRetrievedInterface
 {
     /**
+     * Information about the authorization flow the payment went through. Null if the payment transitioned
+     * immediately to authorized or failed.
+     *
      * @return ConfigurationInterface|null
      */
     public function getAuthorizationFlowConfig(): ?ConfigurationInterface;
 
     /**
+     * The date and time that TrueLayer determined that the payment was ready to be credited.
+     *
      * @return \DateTimeInterface|null
      */
     public function getCreditableAt(): ?\DateTimeInterface;

src/Interfaces/Payment/PaymentAuthorizingInterface.php

@@ -7,14 +7,22 @@
 use TrueLayer\Interfaces\Payment\AuthorizationFlow\ActionInterface;
 use TrueLayer\Interfaces\Payment\AuthorizationFlow\ConfigurationInterface;
 
+/**
+ * The payment's authorization_flow has started, but authorization has not completed yet.
+ */
 interface PaymentAuthorizingInterface extends PaymentRetrievedInterface
 {
     /**
+     * The next action the user must take in the authorization flow, such as selecting a provider or being
+     * redirected.
+     *
      * @return ActionInterface|null
      */
     public function getAuthorizationFlowNextAction(): ?ActionInterface;
 
     /**
+     * Information about the authorization flow the payment went through.
+     *
      * @return ConfigurationInterface|null
      */
     public function getAuthorizationFlowConfig(): ?ConfigurationInterface;

src/Interfaces/Payment/PaymentCreatedInterface.php

@@ -12,29 +12,44 @@
 use TrueLayer\Interfaces\HppInterface;
 use TrueLayer\Interfaces\Payment\AuthorizationFlow\AuthorizationFlowAuthorizingInterface;
 
+/**
+ * The newly created payment, as returned by the payment creation response.
+ */
 interface PaymentCreatedInterface extends ArrayableInterface
 {
     /**
+     * The unique ID of the payment.
+     *
      * @return string
      */
     public function getId(): string;
 
     /**
+     * A payment token in JWT format, with a limited scope that is authorised to be used with this single
+     * payment.
+     *
      * @return string
      */
     public function getResourceToken(): string;
 
     /**
+     * The unique ID of the user. If a user ID wasn't passed in the request body while creating the
+     * payment, TrueLayer generates one and returns it here.
+     *
      * @return string
      */
     public function getUserId(): string;
 
     /**
+     * The Hosted Payments Page URI, if a hosted_page was requested on creation.
+     *
      * @return string|null
      */
     public function getHostedPageUri(): ?string;
 
     /**
+     * Builds the Hosted Payments Page URL for this payment.
+     *
      * @return HppInterface
      */
     public function hostedPaymentsPage(): HppInterface;
@@ -54,13 +69,18 @@ public function hostedPaymentsPage(): HppInterface;
     public function startAuthorization(string $returnUri): AuthorizationFlowAuthorizingInterface;
 
     /**
+     * Starts building a request to manually start the authorization flow for this payment.
+     *
      * @throws InvalidArgumentException
      *
      * @return StartAuthorizationFlowRequestInterface
      */
     public function authorizationFlow(): StartAuthorizationFlowRequestInterface;
 
     /**
+     * Retrieves the full payment details, equivalent to calling `getPayment()` on the client with this
+     * payment's ID.
+     *
      * @throws ApiRequestJsonSerializationException
      * @throws ApiResponseUnsuccessfulException
      *

src/Interfaces/Payment/PaymentExecutedInterface.php

@@ -6,19 +6,29 @@
 
 use TrueLayer\Interfaces\Payment\AuthorizationFlow\ConfigurationInterface;
 
+/**
+ * An executed payment - the bank has accepted the payment.
+ */
 interface PaymentExecutedInterface extends PaymentRetrievedInterface
 {
     /**
+     * The date and time the payment executed at.
+     *
      * @return \DateTimeInterface
      */
     public function getExecutedAt(): \DateTimeInterface;
 
     /**
+     * Information about the authorization flow the payment went through. Null if the payment transitioned
+     * immediately to authorized or failed.
+     *
      * @return ConfigurationInterface|null
      */
     public function getAuthorizationFlowConfig(): ?ConfigurationInterface;
 
     /**
+     * The date and time that TrueLayer determined that the payment was ready to be credited.
+     *
      * @return \DateTimeInterface|null
      */
     public function getCreditableAt(): ?\DateTimeInterface;

src/Interfaces/Payment/PaymentFailedAttemptInterface.php

@@ -6,19 +6,29 @@
 
 use TrueLayer\Interfaces\ArrayableInterface;
 
+/**
+ * A failed payment attempt, recorded when payment retries are enabled. Contains details about when the
+ * attempt failed and why.
+ */
 interface PaymentFailedAttemptInterface extends ArrayableInterface
 {
     /**
+     * The sequential number of this payment attempt.
+     *
      * @return int
      */
     public function getAttemptNumber(): int;
 
     /**
+     * The date and time this payment attempt failed.
+     *
      * @return \DateTimeInterface
      */
     public function getFailedAt(): \DateTimeInterface;
 
     /**
+     * The reason this attempt failed. Handle unexpected values gracefully as an unknown failure.
+     *
      * @return string
      */
     public function getFailureReason(): string;

src/Interfaces/Payment/PaymentFailedInterface.php

@@ -4,24 +4,36 @@
 
 namespace TrueLayer\Interfaces\Payment;
 
+/**
+ * A failed payment - it was authorized successfully, but the money did not move.
+ */
 interface PaymentFailedInterface extends PaymentFailureInterface
 {
     /**
+     * The date and time that TrueLayer determined that the payment was ready to be credited.
+     *
      * @return \DateTimeInterface|null
      */
     public function getCreditableAt(): ?\DateTimeInterface;
 
     /**
+     * The date and time at which TrueLayer determined that the payment's settlement was stalled, based on
+     * the client's chosen delay or the default one.
+     *
      * @return \DateTimeInterface|null
      */
     public function getSettlementStalledAt(): ?\DateTimeInterface;
 
     /**
+     * The date and time the payment was reversed, if it was.
+     *
      * @return \DateTimeInterface|null
      */
     public function getReversedAt(): ?\DateTimeInterface;
 
     /**
+     * The reason for the payment reversal, one of `corrected`, `failed` or `disputed`.
+     *
      * @return string|null
      */
     public function getReversalReason(): ?string;

src/Interfaces/Payment/PaymentFailureInterface.php

@@ -6,24 +6,39 @@
 
 use TrueLayer\Interfaces\Payment\AuthorizationFlow\ConfigurationInterface;
 
+/**
+ * Fields shared by a payment that was authorized successfully, but the money did not move (either
+ * permanently, via `PaymentFailedInterface`, or for a single retried attempt, via
+ * `PaymentAttemptFailedInterface`).
+ */
 interface PaymentFailureInterface extends PaymentRetrievedInterface
 {
     /**
+     * The date and time the payment was marked as failed.
+     *
      * @return \DateTimeInterface
      */
     public function getFailedAt(): \DateTimeInterface;
 
     /**
+     * The status the payment was in when it failed, one of `authorization_required`, `authorizing`,
+     * `authorized` or `executed`.
+     *
      * @return string
      */
     public function getFailureStage(): string;
 
     /**
+     * The reason the payment failed. Handle unexpected values gracefully as an unknown failure.
+     *
      * @return string|null
      */
     public function getFailureReason(): ?string;
 
     /**
+     * Information about the authorization flow the payment went through. Null if the payment transitioned
+     * immediately to authorized or failed.
+     *
      * @return ConfigurationInterface|null
      */
     public function getAuthorizationFlowConfig(): ?ConfigurationInterface;

src/Interfaces/Payment/PaymentHostedPageInterface.php

@@ -4,6 +4,10 @@
 
 namespace TrueLayer\Interfaces\Payment;
 
+/**
+ * Configures an auto-constructed Hosted Payments Page URI, returned on the payment creation response.
+ * Cannot be provided if starting the authorization flow explicitly.
+ */
 interface PaymentHostedPageInterface
 {
     /**
@@ -12,6 +16,9 @@ interface PaymentHostedPageInterface
     public function getReturnUri(): ?string;
 
     /**
+     * The URI where the user will be redirected after the authorization flow has completed on the hosted
+     * page. Must be registered as an allowed redirect URI in the Console.
+     *
      * @param string $returnUri
      *
      * @return PaymentHostedPageInterface
@@ -24,6 +31,8 @@ public function returnUri(string $returnUri): PaymentHostedPageInterface;
     public function getCountryCode(): ?string;
 
     /**
+     * The country code of the user, used to determine which banks to show on the hosted page initially.
+     *
      * @param string $countryCode ISO 3166-1 alpha-2 country code
      *
      * @return PaymentHostedPageInterface
@@ -36,6 +45,9 @@ public function countryCode(string $countryCode): PaymentHostedPageInterface;
     public function getLanguageCode(): ?string;
 
     /**
+     * The language code of the user, used to determine which language to show on the hosted page,
+     * overriding the browser's locale.
+     *
      * @param string $languageCode ISO 639-1 language code
      *
      * @return PaymentHostedPageInterface
@@ -48,6 +60,9 @@ public function languageCode(string $languageCode): PaymentHostedPageInterface;
     public function getMaxWaitForResult(): ?int;
 
     /**
+     * The maximum time to wait for a result from the hosted page after the user has completed the
+     * authorization flow.
+     *
      * @param int $maxWaitForResult Seconds to wait for a result, between 0 and 60
      *
      * @return PaymentHostedPageInterface