From 3437cba042ee695dde71497dad2fa2c538ecae32 Mon Sep 17 00:00:00 2001
From: Anatoliy Poloz <t0ly.od@yandex.ru>
Date: Tue, 16 Jun 2026 22:25:04 +0300
Subject: [PATCH] payoff list

---
 .../Payouts/PayOffsListResponseData.php       | 36 +++++++
 .../Payouts/PayoffListItemData.php            | 58 +++++++++++
 src/Data/Shared/PaginationData.php            | 30 ++++++
 .../Payouts/GetPayoffsRequest.php             | 96 +++++++++++++++++++
 4 files changed, 220 insertions(+)
 create mode 100644 src/Data/NominalAccounts/Payouts/PayOffsListResponseData.php
 create mode 100644 src/Data/NominalAccounts/Payouts/PayoffListItemData.php
 create mode 100644 src/Data/Shared/PaginationData.php
 create mode 100644 src/Requests/NominalAccounts/Payouts/GetPayoffsRequest.php

diff --git a/src/Data/NominalAccounts/Payouts/PayOffsListResponseData.php b/src/Data/NominalAccounts/Payouts/PayOffsListResponseData.php
new file mode 100644
index 0000000..8df2203
--- /dev/null
+++ b/src/Data/NominalAccounts/Payouts/PayOffsListResponseData.php
@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+/*
+// MODULE_CONTRACT: Defines the data structure for the GET /payoffs list response.
+// RESPONSIBILITY: To hold and type-safely represent the paginated list of payoffs returned by the bank API.
+// INPUTS: Raw JSON object from the API response.
+// OUTPUTS: A structured object containing pagination metadata, account number, and an array of payoff items.
+// LINKS: Requests/NominalAccounts/Payouts/GetPayoffsRequest.php, PayoffListItemData.php
+*/
+
+namespace Apoloz\AlfaBank\Data\NominalAccounts\Payouts;
+
+use Apoloz\AlfaBank\Data\Shared\PaginationData;
+use Spatie\LaravelData\Data;
+
+/**
+ * DTO for the GET /payoffs list response.
+ *
+ * @property-read PaginationData $pagination Pagination metadata
+ * @property-read string $accountNumber Номер номинального счёта
+ * @property-read PayoffListItemData[] $payoffs Список выплат
+ */
+class PayOffsListResponseData extends Data
+{
+    /**
+     * @param  PaginationData  $pagination  Pagination metadata
+     * @param  string  $accountNumber  Номер номинального счёта
+     * @param  PayoffListItemData[]  $payoffs  Список выплат
+     */
+    public function __construct(
+        public PaginationData $pagination,
+        public string $accountNumber,
+        public array $payoffs,
+    ) {}
+}
diff --git a/src/Data/NominalAccounts/Payouts/PayoffListItemData.php b/src/Data/NominalAccounts/Payouts/PayoffListItemData.php
new file mode 100644
index 0000000..04ef57c
--- /dev/null
+++ b/src/Data/NominalAccounts/Payouts/PayoffListItemData.php
@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+/*
+// MODULE_CONTRACT: Defines the data structure for a single payoff item in the list response from GET /payoffs.
+// RESPONSIBILITY: To hold and type-safely represent comprehensive information about a single payoff from the list endpoint.
+// INPUTS: Raw JSON object from the API response.
+// OUTPUTS: A structured object containing payoff details.
+// LINKS: PayOffsListResponseData.php, Requests/NominalAccounts/Payouts/GetPayoffsRequest.php
+*/
+
+namespace Apoloz\AlfaBank\Data\NominalAccounts\Payouts;
+
+use Spatie\LaravelData\Data;
+
+/**
+ * DTO for a single payoff item in the GET /payoffs list response.
+ *
+ * Based on OpenAPI PayoffItemResponse schema.
+ * Поля payer и recipient — array (raw JSON) вместо typed DTO, потому что
+ * существующие PayerInfoData/RecipientInfoData имеют другую структуру полей
+ * (accountNumber вместо bankAccount, нет bankName/bankBik/beneficiaryId в нужных местах)
+ * и их модификация может сломать DetailedPayoffData.
+ *
+ * @property-read string $id Идентификатор платежа (UUID)
+ * @property-read string|null $dealId Идентификатор сделки (UUID)
+ * @property-read string|null $stepId Идентификатор этапа сделки (UUID)
+ * @property-read string $payoffType Тип платежа
+ * @property-read string $type Тип платежа (PayoffType)
+ * @property-read string $channel Направление: INTERNAL|EXTERNAL
+ * @property-read string $requisiteType Тип реквизитов
+ * @property-read int $amount Сумма в рублях
+ * @property-read string|null $purpose Назначение платежа
+ * @property-read array|null $payer Плательщик (raw JSON)
+ * @property-read array|null $recipient Получатель (raw JSON)
+ * @property-read string $status Статус
+ * @property-read string|null $createdAt Дата создания (YYYY-MM-DD)
+ * @property-read string|null $updatedAt Дата обновления (YYYY-MM-DD)
+ */
+class PayoffListItemData extends Data
+{
+    public function __construct(
+        public string $id,
+        public ?string $dealId = null,
+        public ?string $stepId = null,
+        public string $payoffType = 'REGULAR',
+        public string $type = 'REGULAR',
+        public string $channel = 'EXTERNAL',
+        public string $requisiteType = 'ACCOUNT',
+        public int $amount = 0,
+        public ?string $purpose = null,
+        public ?array $payer = null,
+        public ?array $recipient = null,
+        public string $status = 'NEW',
+        public ?string $createdAt = null,
+        public ?string $updatedAt = null,
+    ) {}
+}
diff --git a/src/Data/Shared/PaginationData.php b/src/Data/Shared/PaginationData.php
new file mode 100644
index 0000000..5327330
--- /dev/null
+++ b/src/Data/Shared/PaginationData.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+/*
+// MODULE_CONTRACT: Defines the data structure for pagination metadata.
+// RESPONSIBILITY: To hold and type-safely represent pagination information from paginated API responses.
+// INPUTS: Raw JSON object from the API response.
+// OUTPUTS: A structured object containing pagination details.
+// LINKS: NominalAccounts/Payouts/PayOffsListResponseData.php
+*/
+
+namespace Apoloz\AlfaBank\Data\Shared;
+
+use Spatie\LaravelData\Data;
+
+/**
+ * DTO for pagination metadata.
+ *
+ * @property-read int $limit  Maximum items per page
+ * @property-read int $offset Number of items skipped
+ * @property-read int $totalCount Total items across all pages
+ */
+class PaginationData extends Data
+{
+    public function __construct(
+        public int $limit,
+        public int $offset,
+        public int $totalCount,
+    ) {}
+}
diff --git a/src/Requests/NominalAccounts/Payouts/GetPayoffsRequest.php b/src/Requests/NominalAccounts/Payouts/GetPayoffsRequest.php
new file mode 100644
index 0000000..1f39742
--- /dev/null
+++ b/src/Requests/NominalAccounts/Payouts/GetPayoffsRequest.php
@@ -0,0 +1,96 @@
+<?php
+
+declare(strict_types=1);
+/*
+// MODULE_CONTRACT: Represents the API call to retrieve a list of payoffs by account number.
+// RESPONSIBILITY: To define the GET request for fetching a paginated list of payoffs with optional filters.
+// INPUTS: accountNumber (required), limit, offset, channel, status, createdDateFrom/To, updatedDateFrom/To.
+// OUTPUTS: PayOffsListResponseData (DTO).
+// LINKS: Data/NominalAccounts/Payouts/PayOffsListResponseData.php
+*/
+
+namespace Apoloz\AlfaBank\Requests\NominalAccounts\Payouts;
+
+use Apoloz\AlfaBank\Data\NominalAccounts\Payouts\PayOffsListResponseData;
+use Saloon\Enums\Method;
+use Saloon\Http\Request;
+use Saloon\Http\Response;
+
+/**
+ * Request to list payoffs by account number (GET /api/na/jp/v1/payoffs).
+ *
+ * Supports filtering by status, date range, and pagination.
+ */
+class GetPayoffsRequest extends Request
+{
+    protected Method $method = Method::GET;
+
+    /**
+     * @param  string  $accountNumber  Номер номинального счёта (required, 20 digits)
+     * @param  int|null  $limit  Количество объектов на странице (1-100, default 100)
+     * @param  int|null  $offset  Количество объектов, которые необходимо пропустить (default 0)
+     * @param  string|null  $channel  Направление платежа: EXTERNAL|INTERNAL
+     * @param  string|null  $status  Статус платежа: NEW|IN_PROGRESS|FAILED|AWAIT_EXTERNAL|READY
+     * @param  string|null  $createdDateFrom  Начало выборки по дате создания (YYYY-MM-DD)
+     * @param  string|null  $createdDateTo  Конец выборки по дате создания (YYYY-MM-DD)
+     * @param  string|null  $updatedDateFrom  Начало выборки по дате обновления (YYYY-MM-DD)
+     * @param  string|null  $updatedDateTo  Конец выборки по дате обновления (YYYY-MM-DD)
+     */
+    public function __construct(
+        protected string $accountNumber,
+        protected ?int $limit = 100,
+        protected ?int $offset = 0,
+        protected ?string $channel = null,
+        protected ?string $status = null,
+        protected ?string $createdDateFrom = null,
+        protected ?string $createdDateTo = null,
+        protected ?string $updatedDateFrom = null,
+        protected ?string $updatedDateTo = null,
+    ) {}
+
+    public function resolveEndpoint(): string
+    {
+        $params = [];
+
+        $params['accountNumber'] = $this->accountNumber;
+
+        if ($this->limit !== null) {
+            $params['limit'] = $this->limit;
+        }
+
+        if ($this->offset !== null) {
+            $params['offset'] = $this->offset;
+        }
+
+        if ($this->channel !== null) {
+            $params['channel'] = $this->channel;
+        }
+
+        if ($this->status !== null) {
+            $params['status'] = $this->status;
+        }
+
+        if ($this->createdDateFrom !== null) {
+            $params['createdDateFrom'] = $this->createdDateFrom;
+        }
+
+        if ($this->createdDateTo !== null) {
+            $params['createdDateTo'] = $this->createdDateTo;
+        }
+
+        if ($this->updatedDateFrom !== null) {
+            $params['updatedDateFrom'] = $this->updatedDateFrom;
+        }
+
+        if ($this->updatedDateTo !== null) {
+            $params['updatedDateTo'] = $this->updatedDateTo;
+        }
+
+        return '/api/na/jp/v1/payoffs?' . http_build_query($params);
+    }
+
+    public function createDtoFromResponse(Response $response): PayOffsListResponseData
+    {
+        return PayOffsListResponseData::from($response->json());
+    }
+}