[ACL-69] Merchant account transactions

CHANGELOG.md

@@ -9,6 +9,7 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- Support for retrieving merchant account transactions ([#81](https://github.com/TrueLayer/truelayer-php/pull/81))
 - Support for `creditable_at` in Authorised, Executed, Settled, Failed payments ([#82](https://github.com/TrueLayer/truelayer-php/pull/82))
 - Enabled PHP 8.4 in CI test matrix. Excluded the lowest dependencies versions to overcome incompatibility issues ([#83](https://github.com/TrueLayer/truelayer-php/pull/83))
 

README.md

@@ -1020,6 +1020,22 @@ foreach ($merchantAccount->getAccountIdentifiers() as $accountIdentifier) {
 }
 ```
 
+Retrieving a merchant account's list of transactions:
+
+```php
+$account = $client->getMerchantAccount('a2dcee6d-7a00-414d-a1e6-8a2b23169e00');
+
+$from = (new DateTime())->sub(new DateInterval("PT6H"));
+$to = new DateTime();
+
+$transactions = $account->getTransactions($from, $to);
+
+foreach ($transactions as $transaction) {
+    // See MerchantAccountRetrievedTransactionInterface and
+    // the interfaces that extend it for available methods.
+}
+```
+
 <a name="signup-plus"></a>
 
 # SignUp Plus

config/bindings.php

@@ -92,6 +92,14 @@
     Interfaces\Remitter\RemitterVerification\AutomatedRemitterVerificationInterface::class => Entities\Remitter\RemitterVerification\AutomatedRemitterVerification::class,
 
     Interfaces\MerchantAccount\MerchantAccountInterface::class => Entities\MerchantAccount\MerchantAccount::class,
+    Interfaces\MerchantAccount\Transactions\MerchantAccountTransactionRetrievedInterface::class => Entities\MerchantAccount\Transactions\MerchantAccountTransactionRetrieved::class,
+    Interfaces\MerchantAccount\Transactions\MerchantAccountPaymentInterface::class => Entities\MerchantAccount\Transactions\MerchantAccountPayment::class,
+    Interfaces\MerchantAccount\Transactions\MerchantAccountExternalPaymentInterface::class => Entities\MerchantAccount\Transactions\MerchantAccountExternalPayment::class,
+    Interfaces\MerchantAccount\Transactions\MerchantAccountPendingPayoutInterface::class => Entities\MerchantAccount\Transactions\MerchantAccountPendingPayout::class,
+    Interfaces\MerchantAccount\Transactions\MerchantAccountExecutedPayoutInterface::class => Entities\MerchantAccount\Transactions\MerchantAccountExecutedPayout::class,
+    Interfaces\MerchantAccount\Transactions\MerchantAccountRefundInterface::class => Entities\MerchantAccount\Transactions\MerchantAccountRefund::class,
+    Interfaces\MerchantAccount\Transactions\Returns\MerchantAccountExternalPaymentReturnIdentifiedInterface::class => Entities\MerchantAccount\Transactions\Returns\MerchantAccountExternalPaymentReturnIdentified::class,
+    Interfaces\MerchantAccount\Transactions\Returns\MerchantAccountExternalPaymentReturnUnknownInterface::class => Entities\MerchantAccount\Transactions\Returns\MerchantAccountExternalPaymentReturnUnknown::class,
 
     Interfaces\Webhook\PaymentAuthorizedEventInterface::class => Entities\Webhook\PaymentAuthorizedEvent::class,
     Interfaces\Webhook\PaymentExecutedEventInterface::class => Entities\Webhook\PaymentExecutedEvent::class,

config/discriminations.php

@@ -6,6 +6,8 @@
 use TrueLayer\Constants\AuthorizationFlowActionTypes;
 use TrueLayer\Constants\AuthorizationFlowStatusTypes;
 use TrueLayer\Constants\BeneficiaryTypes;
+use TrueLayer\Constants\MerchantAccountPayoutStatuses;
+use TrueLayer\Constants\MerchantAccountTransactionTypes;
 use TrueLayer\Constants\PaymentMethods;
 use TrueLayer\Constants\PaymentStatus;
 use TrueLayer\Constants\PayoutStatus;
@@ -119,4 +121,16 @@
         'discriminate_on' => 'type',
         RemitterVerificationTypes::AUTOMATED => Interfaces\Remitter\RemitterVerification\AutomatedRemitterVerificationInterface::class,
     ],
+    Interfaces\MerchantAccount\Transactions\MerchantAccountTransactionRetrievedInterface::class => [
+        'discriminate_on' => 'type',
+        MerchantAccountTransactionTypes::EXTERNAL_PAYMENT => Interfaces\MerchantAccount\Transactions\MerchantAccountExternalPaymentInterface::class,
+        MerchantAccountTransactionTypes::PAYOUT => Interfaces\MerchantAccount\Transactions\MerchantAccountPayoutInterface::class,
+        MerchantAccountTransactionTypes::REFUND => Interfaces\MerchantAccount\Transactions\MerchantAccountRefundInterface::class,
+        MerchantAccountTransactionTypes::MERCHANT_ACCOUNT_PAYMENT => Interfaces\MerchantAccount\Transactions\MerchantAccountPaymentInterface::class,
+    ],
+    Interfaces\MerchantAccount\Transactions\MerchantAccountPayoutInterface::class => [
+        'discriminate_on' => 'status',
+        MerchantAccountPayoutStatuses::EXECUTED_PAYOUT => Interfaces\MerchantAccount\Transactions\MerchantAccountExecutedPayoutInterface::class,
+        MerchantAccountPayoutStatuses::PENDING_PAYOUT => Interfaces\MerchantAccount\Transactions\MerchantAccountPendingPayoutInterface::class,
+    ],
 ];

src/Constants/MerchantAccountPayoutStatuses.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TrueLayer\Constants;
+
+class MerchantAccountPayoutStatuses
+{
+    public const EXECUTED_PAYOUT = 'executed';
+    public const PENDING_PAYOUT = 'pending';
+}

src/Constants/MerchantAccountTransactionTypes.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TrueLayer\Constants;
+
+class MerchantAccountTransactionTypes
+{
+    public const MERCHANT_ACCOUNT_PAYMENT = 'merchant_account_payment';
+    public const EXTERNAL_PAYMENT = 'external_payment';
+    public const PAYOUT = 'payout';
+    public const REFUND = 'refund';
+}

src/Entities/MerchantAccount/MerchantAccount.php

@@ -5,11 +5,17 @@
 namespace TrueLayer\Entities\MerchantAccount;
 
 use TrueLayer\Entities\Entity;
+use TrueLayer\Exceptions\InvalidArgumentException;
 use TrueLayer\Interfaces\AccountIdentifier\AccountIdentifierInterface;
+use TrueLayer\Interfaces\HasApiFactoryInterface;
 use TrueLayer\Interfaces\MerchantAccount\MerchantAccountInterface;
+use TrueLayer\Interfaces\MerchantAccount\Transactions\MerchantAccountTransactionRetrievedInterface;
+use TrueLayer\Traits\ProvidesApiFactory;
 
-final class MerchantAccount extends Entity implements MerchantAccountInterface
+final class MerchantAccount extends Entity implements MerchantAccountInterface, HasApiFactoryInterface
 {
+    use ProvidesApiFactory;
+
     /**
      * @var string
      */
@@ -103,4 +109,18 @@ public function getAccountHolderName(): string
     {
         return $this->accountHolderName;
     }
+
+    /**
+     * @param \DateTimeInterface $from
+     * @param \DateTimeInterface $to
+     *
+     * @return array|MerchantAccountTransactionRetrievedInterface[]
+     * @throws InvalidArgumentException
+     */
+    public function getTransactions(\DateTimeInterface $from, \DateTimeInterface $to): array {
+        $data = $this->getApiFactory()->merchantAccountsApi()
+            ->listTransactions($this->id, $from, $to);
+
+        return $this->entityFactory->makeMany(MerchantAccountTransactionRetrievedInterface::class, $data);
+    }
 }

src/Entities/MerchantAccount/Transactions/MerchantAccountExecutedPayout.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TrueLayer\Entities\MerchantAccount\Transactions;
+
+use TrueLayer\Interfaces\MerchantAccount\Transactions\MerchantAccountExecutedPayoutInterface;
+
+class MerchantAccountExecutedPayout extends MerchantAccountPayout implements MerchantAccountExecutedPayoutInterface
+{
+    /**
+     * @var string
+     */
+    protected string $returnedBy;
+
+    /**
+     * @var string
+     */
+    protected string $schemeId;
+
+    /**
+     * @return string[]
+     */
+    protected function arrayFields(): array
+    {
+        return \array_merge(parent::arrayFields(), [
+            'returned_by',
+            'scheme_id',
+        ]);
+    }
+
+    /**
+     * @return string|null
+     */
+    public function getReturnedBy(): ?string
+    {
+        return $this->returnedBy ?? null;
+    }
+
+    /**
+     * @return string|null
+     */
+    public function getSchemeId(): ?string
+    {
+        return $this->schemeId ?? null;
+    }
+}

src/Entities/MerchantAccount/Transactions/MerchantAccountExternalPayment.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TrueLayer\Entities\MerchantAccount\Transactions;
+
+use TrueLayer\Interfaces\MerchantAccount\Transactions\MerchantAccountExternalPaymentInterface;
+use TrueLayer\Interfaces\MerchantAccount\Transactions\Returns\MerchantAccountExternalPaymentReturnInterface;
+
+class MerchantAccountExternalPayment extends MerchantAccountTransactionRetrieved implements MerchantAccountExternalPaymentInterface
+{
+    /**
+     * @var \DateTimeInterface
+     */
+    protected \DateTimeInterface $settledAt;
+
+    /**
+     * @var MerchantAccountExternalPaymentReturnInterface
+     */
+    protected MerchantAccountExternalPaymentReturnInterface $returnedFor;
+
+    /**
+     * @var array|string[]
+     */
+    protected array $casts = [
+        'settled_at' => \DateTimeInterface::class,
+    ];
+
+    /**
+     * @return string[]
+     */
+    protected function arrayFields(): array
+    {
+        return \array_merge(parent::arrayFields(), [
+            'settled_at',
+            'returned_for',
+        ]);
+    }
+
+    /**
+     * @return \DateTimeInterface
+     */
+    public function getSettledAt(): \DateTimeInterface
+    {
+        return $this->settledAt;
+    }
+
+    /**
+     * @return MerchantAccountExternalPaymentReturnInterface|null
+     */
+    public function getRefundFor(): ?MerchantAccountExternalPaymentReturnInterface
+    {
+        return $this->returnedFor ?? null;
+    }
+}

src/Entities/MerchantAccount/Transactions/MerchantAccountPayment.php

@@ -0,0 +1,84 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TrueLayer\Entities\MerchantAccount\Transactions;
+
+use TrueLayer\Interfaces\MerchantAccount\Transactions\MerchantAccountPaymentInterface;
+use TrueLayer\Interfaces\Payout\Beneficiary\PaymentSourceBeneficiaryInterface;
+
+class MerchantAccountPayment extends MerchantAccountTransactionRetrieved implements MerchantAccountPaymentInterface
+{
+    /**
+     * @var \DateTimeInterface
+     */
+    protected \DateTimeInterface $settledAt;
+
+    /**
+     * @var PaymentSourceBeneficiaryInterface
+     */
+    protected PaymentSourceBeneficiaryInterface $paymentSource;
+
+    /**
+     * @var string
+     */
+    protected string $paymentId;
+
+    /**
+     * @var array<string, string>
+     */
+    protected array $metadata;
+
+    /**
+     * @var array|string[]
+     */
+    protected array $casts = [
+        'settled_at' => \DateTimeInterface::class,
+        'payment_source' => PaymentSourceBeneficiaryInterface::class,
+    ];
+
+    /**
+     * @return string[]
+     */
+    protected function arrayFields(): array
+    {
+        return \array_merge(parent::arrayFields(), [
+            'settled_at',
+            'payment_id',
+            'payment_source',
+            'metadata',
+        ]);
+    }
+
+    /**
+     * @return \DateTimeInterface
+     */
+    public function getSettledAt(): \DateTimeInterface
+    {
+        return $this->settledAt;
+    }
+
+    /**
+     * @return PaymentSourceBeneficiaryInterface
+     */
+    public function getPaymentSource(): PaymentSourceBeneficiaryInterface
+    {
+        return $this->paymentSource;
+    }
+
+    /**
+     * @return string
+     */
+    public function getPaymentId(): string
+    {
+        return $this->paymentId;
+    }
+
+    /**
+     * @return string[]
+     */
+    public function getMetadata(): array
+    {
+        return $this->metadata ?? [];
+    }
+}