saloon update

refactor(error): handling
doc(test-payin) added
2026-04-25 13:59:25 +03:00 · 2026-04-07 18:47:53 +03:00 · 2026-04-07 18:44:27 +03:00 · 2026-04-05 09:37:54 +03:00 · 2026-04-02 16:45:41 +03:00
7 changed files with 752 additions and 60 deletions
--- a/_docs/alfabank/payin_and_kyc/продукты_и_сервисы/Номинальные_счета/instrukciya_potestirovaniyu_identifikacii_popolneniya/Инструкция-по-тестированию.md
+++ b/_docs/alfabank/payin_and_kyc/продукты_и_сервисы/Номинальные_счета/instrukciya_potestirovaniyu_identifikacii_popolneniya/Инструкция-по-тестированию.md
@@ -0,0 +1,137 @@
+какой email технической поддержки ?
+
+10:36
+
+Доставлено
+
+Для связи с технической поддержкой используйте электронную почту alfa\_api@alfabank.ru.
+
+10:36
+
+как происходит flow регистрации бенифициара ?
+
+10:53
+
+Доставлено
+
+Для регистрации бенефициара необходимо выполнить следующие шаги:
+
+1.  1.
+    
+    **Создать запрос на регистрацию бенефициара** с помощью метода:
+    
+    -   •
+        
+        **Песочница**: `POST https://sandbox.alfabank.ru/api/na/jp/v1/beneficiaries`
+        
+    -   •
+        
+        **Пром**: `POST https://baas.alfabank.ru/api/na/jp/v1/beneficiaries`
+        
+    
+    При этом нужно учитывать, что в зависимости от типа бенефициара поля запроса заполняются по-разному.
+    
+2.  2.
+    
+3.  3.
+    
+
+При успешной регистрации бенефициару присваивается уникальный идентификатор — `beneficiaryId`.
+
+**Важно:** учёт денежных средств на виртуальных счетах бенефициаров будет вестись корректно только при условии, что владелец номинального счёта не использует другие каналы вывода средств с номинального счёта (например, банк-клиент, платёжные поручения на бумажном носителе, сервисы Alfa API для осуществления переводов и другие).
+
+Ссылки на документацию:
+
+-   •
+    
+-   •
+    
+-   •
+    
+
+10:53
+
+а как же socring ?
+
+10:55
+
+Доставлено
+
+Для проверки актуальности ранее зарегистрированных данных о бенефициаре используются следующие методы:
+
+1.  1.
+    
+    **«Создание запроса на проверку бенефициара»** — инициирует процесс скоринга бенефициара.
+    
+2.  2.
+    
+    **«Получение статуса запроса»** — позволяет отслеживать статус ранее созданного запроса на проверку.
+    
+
+**Ссылки на документацию:**
+
+-   •
+    
+-   •
+    
+
+10:55
+
+каким образом можно пополнить номинальный счёт компании ?
+
+22:24
+
+Доставлено
+
+Депонент (бенефициар) может пополнить номинальный счёт удобным ему способом. После этого владелец номинального счёта должен идентифицировать поступившие денежные средства. Для этого владельцу счёта необходимо выполнить следующие шаги:
+
+1.  1.
+    
+2.  2.
+    
+3.  3.
+    
+
+22:25
+
+каким образом можно пополнить номинальный счёт компании ?
+
+22:25
+
+Доставлено
+
+Депонент (бенефициар) может пополнить номинальный счёт удобным ему способом. После этого владелец номинального счёта должен идентифицировать поступившие денежные средства. Для этого владельцу счёта необходимо выполнить следующие шаги:
+
+1.  1.
+    
+2.  2.
+    
+3.  3.
+    
+
+**Важно:** для работы с сервисом необходимо использовать электронную подпись. Допускается использование сертификата, выпущенного с помощью [сервиса «Электронная подпись»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/signature/articles/intro/intro), или сертификата УКЭП, выпущенного в любом аккредитованном УЦ.
+
+Ссылка на статью с подробным описанием процесса: [Идентификация пополнений номинального счёта](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/intro/intro).
+
+22:25
+
+а что это значит "любым удобным способом"? каким например ?
+
+22:25
+
+Доставлено
+
+В предоставленной документации нет конкретного перечня способов пополнения номинального счёта. Однако указано, что депонент (бенефициар) может пополнить номинальный счёт удобным ему способом. После этого владелец номинального счёта должен идентифицировать поступившие денежные средства с помощью специальных методов API.
+
+Для идентификации пополнений владелец счёта может использовать следующие методы:
+
+1.  1.
+    
+2.  2.
+    
+3.  3.
+    
+
+Для более детальной информации о возможных способах пополнения номинального счёта рекомендуется обратиться на почту alfa\_api@alfabank.ru.
+
+22:25
--- a/_docs/alfabank/payin_and_kyc/продукты_и_сервисы/Номинальные_счета/instrukciya_potestirovaniyu_identifikacii_popolneniya/Интеграция
+++ b/_docs/alfabank/payin_and_kyc/продукты_и_сервисы/Номинальные_счета/instrukciya_potestirovaniyu_identifikacii_popolneniya/Интеграция
@@ -0,0 +1,153 @@
+---
+title: "Интеграция с Альфа-Банком: API, документация, примеры кода"
+source: "https://developers.alfabank.ru/products/alfa-api/documentation/articles/sandbox/articles/nominal-accounts/articles/intro/intro"
+author:
+published:
+created: 2026-04-07
+description: "Описания API-методов, примеры запросов, инструкции по настройке интеграции для работы с продуктами и сервисами Альфа-Банка"
+tags:
+  - "clippings"
+---
+#### Инструкция по тестированию
+
+Рекомендации по тестированию [номинальных счетов](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/intro/intro).
+
+##### Идентификация пополнений
+
+Для тестирования методов для идентификации пополнений номинального счёта предварительно необходимо создать тестовое неидентифицированное пополнение с помощью метода [«Создание тестового неидентифицированного пополнения номинального счёта»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/sandbox/articles/nominal-accounts/articles/unidentified-transaction/v1/unidentified-transaction).
+
+В результате успешного запроса будет создано тестовое неидентифицированное пополнение c идентификатором `id`, который далее необходимо будет передать в методе [«Создание запроса на идентификацию пополнения номинального счёта»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/identify/v1/identify).
+
+[Создание тестового неидентифицированного пополнения номинального счёта](https://developers.alfabank.ru/products/alfa-api/documentation/articles/sandbox/articles/nominal-accounts/articles/unidentified-transaction/v1/unidentified-transaction)
+
+API Helper
+
+Beta
+
+---
+
+какой email технической поддержки?
+
+10:36
+
+Доставлено
+
+Для связи с технической поддержкой используйте электронную почту alfa\_api@alfabank.ru.
+
+10:36
+
+как происходит flow регистрации бенифициара?
+
+10:53
+
+Доставлено
+
+Для регистрации бенефициара необходимо выполнить следующие шаги:
+
+1. 1.
+	**Создать запрос на регистрацию бенефициара** с помощью метода:
+	- •
+		**Песочница**: `POST https://sandbox.alfabank.ru/api/na/jp/v1/beneficiaries`
+		- •
+		**Пром**: `POST https://baas.alfabank.ru/api/na/jp/v1/beneficiaries`
+	При этом нужно учитывать, что в зависимости от типа бенефициара поля запроса заполняются по-разному.
+2. 2.
+	**Получить статус запроса** с помощью метода [«Получение статуса запроса»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/get-request-status/v1/get-request-status).
+3. 3.
+	**После регистрации бенефициара необходимо указать его платёжные реквизиты** с помощью метода [«Добавление платёжных реквизитов бенефициара»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/add-requisites/v1/add-requisites).
+
+При успешной регистрации бенефициару присваивается уникальный идентификатор — `beneficiaryId`.
+
+**Важно:** учёт денежных средств на виртуальных счетах бенефициаров будет вестись корректно только при условии, что владелец номинального счёта не использует другие каналы вывода средств с номинального счёта (например, банк-клиент, платёжные поручения на бумажном носителе, сервисы Alfa API для осуществления переводов и другие).
+
+Ссылки на документацию:
+
+- •
+	[Создание запроса на регистрацию бенефициара](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/add-beneficiary/v1/add-beneficiary)
+- •
+	[Получение статуса запроса](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/get-request-status/v1/get-request-status)
+- •
+	[Добавление платёжных реквизитов бенефициара](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/add-requisites/v1/add-requisites)
+
+10:53
+
+а как же socring?
+
+10:55
+
+Доставлено
+
+Для проверки актуальности ранее зарегистрированных данных о бенефициаре используются следующие методы:
+
+1. 1.
+	**«Создание запроса на проверку бенефициара»** — инициирует процесс скоринга бенефициара.
+2. 2.
+	**«Получение статуса запроса»** — позволяет отслеживать статус ранее созданного запроса на проверку.
+
+**Ссылки на документацию:**
+
+- •
+	[Создание запроса на проверку бенефициара](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/beneficiaries/articles/beneficiary-scoring/v1/beneficiary-scoring)
+- •
+	[Получение статуса запроса](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/counterparties/articles/get-request-status/v1/get-request-status)
+
+10:55
+
+каким образом можно пополнить номинальный счёт компании?
+
+22:24
+
+Доставлено
+
+Депонент (бенефициар) может пополнить номинальный счёт удобным ему способом. После этого владелец номинального счёта должен идентифицировать поступившие денежные средства. Для этого владельцу счёта необходимо выполнить следующие шаги:
+
+1. 1.
+	**Получить информацию обо всех неидентифицированных пополнениях** с помощью метода [«Получение списка неидентифицированных пополнений номинального счёта»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/get-unidentified-transactions/v1/get-unidentified-transactions).
+2. 2.
+	**Создать запрос на идентификацию денежных средств** с помощью метода [«Создание запроса на идентификацию пополнения номинального счёта»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/identify/v1/identify).
+3. 3.
+	**Получить статус запроса на идентификацию денежных средств** с помощью метода [«Получение статуса запроса на идентификацию пополнения номинального счёта»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/get-identify-request-status/v1/get-identify-request-status).
+
+22:25
+
+каким образом можно пополнить номинальный счёт компании?
+
+22:25
+
+Доставлено
+
+Депонент (бенефициар) может пополнить номинальный счёт удобным ему способом. После этого владелец номинального счёта должен идентифицировать поступившие денежные средства. Для этого владельцу счёта необходимо выполнить следующие шаги:
+
+1. 1.
+	Получить информацию обо всех неидентифицированных пополнениях с помощью метода [«Получение списка неидентифицированных пополнений номинального счёта»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/get-unidentified-transactions/v1/get-unidentified-transactions).
+2. 2.
+	Создать запрос на идентификацию денежных средств с помощью метода [«Создание запроса на идентификацию пополнения номинального счёта»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/identify/v1/identify).
+3. 3.
+	Получить статус запроса на идентификацию денежных средств с помощью метода [«Получение статуса запроса на идентификацию пополнения номинального счёта»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/get-identify-request-status/v1/get-identify-request-status).
+
+**Важно:** для работы с сервисом необходимо использовать электронную подпись. Допускается использование сертификата, выпущенного с помощью [сервиса «Электронная подпись»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/signature/articles/intro/intro), или сертификата УКЭП, выпущенного в любом аккредитованном УЦ.
+
+Ссылка на статью с подробным описанием процесса: [Идентификация пополнений номинального счёта](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/intro/intro).
+
+22:25
+
+а что это значит "любым удобным способом"? каким например?
+
+22:25
+
+Доставлено
+
+В предоставленной документации нет конкретного перечня способов пополнения номинального счёта. Однако указано, что депонент (бенефициар) может пополнить номинальный счёт удобным ему способом. После этого владелец номинального счёта должен идентифицировать поступившие денежные средства с помощью специальных методов API.
+
+Для идентификации пополнений владелец счёта может использовать следующие методы:
+
+1. 1.
+	Получить информацию обо всех неидентифицированных пополнениях: [«Получение списка неидентифицированных пополнений номинального счёта»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/get-unidentified-transactions/v1/get-unidentified-transactions).
+2. 2.
+	Создать запрос на идентификацию денежных средств: [«Создание запроса на идентификацию пополнения номинального счёта»](https://developers.alfa-bank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/identify/v1/identify).
+3. 3.
+	Получить статус запроса на идентификацию денежных средств: [«Получение статуса запроса на идентификацию пополнения номинального счёта»](https://developers.alfabank.ru/products/alfa-api/documentation/articles/nominal-accounts/articles/identify-transactions/articles/get-identify-request-status/v1/get-identify-request-status).
+
+Для более детальной информации о возможных способах пополнения номинального счёта рекомендуется обратиться на почту alfa\_api@alfabank.ru.
+
+22:25
--- a/_docs/alfabank/payin_and_kyc/продукты_и_сервисы/Номинальные_счета/instrukciya_potestirovaniyu_identifikacii_popolneniya/Создание-тестового.md
+++ b/_docs/alfabank/payin_and_kyc/продукты_и_сервисы/Номинальные_счета/instrukciya_potestirovaniyu_identifikacii_popolneniya/Создание-тестового.md
@@ -0,0 +1,355 @@
+H2H
+
+Песочница
+
+POST https://sandbox.alfabank.ru/api/na/jp/v1/unidentified-transactions
+
+##### Scope
+
+`beneficiary-payments`
+
+[](https://developers.alfabank.ru/assets/developers-portal.docs.alfa-api/articles/sandbox/articles/nominal-accounts/articles/unidentified-transaction/v1/files/unidentified-transaction.yaml)
+
+##### Описание
+
+Метод позволяет создать тестовое неидентифицированное пополнение номинального счёта.
+
+###### Параметры запроса
+
+Атрибут
+
+Описание
+
+Authorization
+
+Accept
+
+stringrequired
+
+application/json
+
+Content-Type
+
+stringrequired
+
+application/json
+
+Атрибут
+
+Описание
+
+documentNumber
+
+stringrequired
+
+Номер платёжного поручения
+
+date
+
+stringrequired
+
+Дата и время пополнения по МСК
+
+amount
+
+stringrequired
+
+Сумма пополнения в рублях
+
+purpose
+
+stringrequired
+
+Назначение платежа
+
+accountNumber
+
+stringrequired
+
+Номер номинального счёта
+
+objectrequired
+
+Информация о плательщике
+
+inn
+
+stringoptional
+
+ИНН плательщика
+
+kpp
+
+stringoptional
+
+КПП плательщика
+
+accountNumber
+
+stringoptional
+
+Номер счёта плательщика
+
+name
+
+stringoptional
+
+Имя плательщика
+
+bankAccount
+
+stringoptional
+
+Номер счёта банка плательщика
+
+bankBik
+
+stringoptional
+
+БИК банка плательщика
+
+bankName
+
+stringoptional
+
+Наименования банка плательщика
+
+```bash
+1curl --location 'https://baas.alfabank.ru/api/na/jp/v1/unidentified-transactions' \
+2--header 'Authorization: Bearer {access-token}' \
+3--header 'Content-Type: application/json' \
+4--header 'Accept: application/json' \
+5--data '{
+6  "documentNumber": "3",
+7  "date": "2026-04-03T13:23:24.439Z",
+8  "amount": 200.9,
+9  "purpose": "Входящая транзакция созданная вручную для тестирования на песочнице",
+10  "accountNumber": "40817810306050000000",
+11  "payer": {
+12    "inn": "221284672706",
+13    "kpp": "641914992",
+14    "accountNumber": "87149728127096890679",
+15    "name": "Имя плательщика",
+16    "bankAccount": "3932755239052037086628",
+17    "bankBik": "108997635",
+18    "bankName": "Наименования банка плательщика"
+19  }
+20}'
+```
+
+###### Параметры ответа
+
+```json
+1{
+2  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6\"",
+3  "documentNumber": "3",
+4  "date": "2025-04-08T10:47:17.927Z",
+5  "amount": 200.9,
+6  "purpose": "Входящая транзакция созданная вручную для тестирования на песочнице",
+7  "accountNumber": "40817810306050000000",
+8  "payer": {
+9    "inn": "221284672706",
+10    "kpp": "641914992",
+11    "accountNumber": "87149728127096890679",
+12    "name": "Имя плательщика",
+13    "bankAccount": "3932755239052037086628",
+14    "bankBik": "108997635",
+15    "bankName": "Наименования банка плательщика"
+16  }
+17}
+```
+
+атрибут
+
+описание
+
+id
+
+stringrequired
+
+Идентификатор операции пополнения
+
+documentNumber
+
+stringrequired
+
+Номер платёжного поручения
+
+date
+
+stringrequired
+
+Дата и время пополнения по МСК
+
+amount
+
+stringrequired
+
+Сумма пополнения в рублях
+
+purpose
+
+stringrequired
+
+Назначение платежа
+
+accountNumber
+
+stringrequired
+
+Номер номинального счёта
+
+objectrequired
+
+Информация о плательщике
+
+inn
+
+stringoptional
+
+ИНН плательщика
+
+kpp
+
+stringoptional
+
+КПП плательщика
+
+accountNumber
+
+stringoptional
+
+Номер счёта плательщика
+
+name
+
+stringoptional
+
+Имя плательщика
+
+bankAccount
+
+stringoptional
+
+Номер счёта банка плательщика
+
+bankBik
+
+stringoptional
+
+БИК банка плательщика
+
+bankName
+
+stringoptional
+
+Наименования банка плательщика
+
+атрибут
+
+описание
+
+error
+
+stringrequired
+
+Код ошибки. Принимает возможные значения:
+
+-   •
+    
+    `invalid_request` — неверные входные параметры запроса
+    
+
+error\_description
+
+stringoptional
+
+Описание ошибки
+
+атрибут
+
+описание
+
+error
+
+stringrequired
+
+Код ошибки. Принимает возможные значения:
+
+-   •
+    
+    `invalid_token` — предоставленный токен просрочен, отозван, имеет неправильный формат или недействителен по другим причинам
+    
+
+error\_description
+
+stringoptional
+
+Описание ошибки
+
+атрибут
+
+описание
+
+error
+
+stringrequired
+
+Код ошибки. Принимает возможные значения:
+
+-   •
+    
+    `insufficient_scope` — у пользователя нет прав на использование запрашиваемого сервиса, доступ к которому не предусмотрен настройками scope
+    
+
+error\_description
+
+stringoptional
+
+Описание ошибки
+
+атрибут
+
+описание
+
+error
+
+stringrequired
+
+Код ошибки. Принимает возможные значения:
+
+-   •
+    
+    `unknown_endpoint` — эндпоинт не найден или неактивен
+    
+
+error\_description
+
+stringoptional
+
+Описание ошибки
+
+Нет тела ответа
+
+атрибут
+
+описание
+
+error
+
+stringrequired
+
+Код ошибки. Принимает возможные значения:
+
+-   •
+    
+    `internal_error` — внутренняя ошибка сервиса при выполнении обработки запроса
+    
+
+error\_description
+
+stringoptional
+
+Описание ошибки
+
+Нет тела ответа
--- a/composer.json
+++ b/composer.json
@@ -1,49 +1,56 @@
 {
-    "name": "apoloz/alfa-bank-sdk",
-    "description": "Unofficial Alfa Bank API SDK for PHP using Saloon and Laravel Data",
-    "type": "library",
-    "license": "MIT",
-    "authors": [
-        {
-            "name": "apoloz",
-            "email": "anatoliy.poloz@gmail.com"
-        }
-    ],
-    "require": {
-        "php": "^8.2",
-        "saloonphp/saloon": "^3.0",
-        "saloonphp/laravel-plugin": "^3.0",
-        "saloonphp/pagination-plugin": "^2.0",
-        "spatie/laravel-data": "^4.0",
-        "guzzlehttp/guzzle": "^7.0",
-        "phpseclib/phpseclib": "^3.0"
-    },
-    "require-dev": {
-        "phpunit/phpunit": "^10.0",
-        "pestphp/pest": "^2.0",
-        "phpstan/phpstan": "^2.1"
-    },
-    "autoload": {
-        "psr-4": {
-            "Apoloz\\AlfaBank\\": "src/"
-        }
-    },
-    "extra": {
-        "laravel": {
-            "providers": [
-                "Apoloz\\AlfaBank\\Laravel\\AlfaBankServiceProvider"
-            ]
-        }
-    },
-    "minimum-stability": "stable",
-    "prefer-stable": true,
-    "scripts": {
-        "test": "vendor/bin/pest",
-        "test-coverage": "vendor/bin/pest --coverage"
-    },
-    "config": {
-        "allow-plugins": {
-            "pestphp/pest-plugin": true
-        }
+  "name": "apoloz/alfa-bank-sdk",
+  "description": "Unofficial Alfa Bank API SDK for PHP using Saloon and Laravel Data",
+  "type": "library",
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "apoloz",
+      "email": "anatoliy.poloz@gmail.com"
    }
+  ],
+  "require": {
+    "php": "^8.4",
+    "saloonphp/saloon": "^4.0",
+    "saloonphp/laravel-plugin": "^4.0",
+    "saloonphp/pagination-plugin": "^2.0",
+    "spatie/laravel-data": "^4.0",
+    "guzzlehttp/guzzle": "^7.0",
+    "phpseclib/phpseclib": "^3.0"
+  },
+  "require-dev": {
+    "phpunit/phpunit": "^10.0",
+    "pestphp/pest": "^2.0",
+    "phpstan/phpstan": "^2.1"
+  },
+  "autoload": {
+    "psr-4": {
+      "Apoloz\\AlfaBank\\": "src/"
+    }
+  },
+  "extra": {
+    "laravel": {
+      "providers": [
+        "Apoloz\\AlfaBank\\Laravel\\AlfaBankServiceProvider"
+      ]
+    }
+  },
+  "minimum-stability": "stable",
+  "prefer-stable": true,
+  "scripts": {
+    "test": "vendor/bin/pest",
+    "test-coverage": "vendor/bin/pest --coverage"
+  },
+  "config": {
+    "allow-plugins": {
+      "pestphp/pest-plugin": true
+    },
+    "audit": {
+      "ignore": {
+        "PKSA-xnj5-w74d-6wmz": "true",
+        "PKSA-rnpm-45mg-w6ht": "true",
+        "PKSA-5szq-gvrg-ttfq": "true"
+      }
+    }
+  }
 }
--- a/src/Sbp/Data/GetQRCdQueryData.php
+++ b/src/Sbp/Data/GetQRCdQueryData.php
@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+/*
+// MODULE_CONTRACT: Defines the data structure for the response when generating an SBP QR Code.
+// RESPONSIBILITY: To provide a strongly-typed structure for the API's response to QR code generation requests, including status, potential error messages, and the generated QR code data (image, payload, ID).
+// INPUTS: Raw array data from the SBP QR Code generation API response.
+// OUTPUTS: An instantiated DTO with properties mapped from the input array.
+// LINKS: Sbp/Requests/GetQrCodeRequest.php, README.md#sbp-api
+*/
+
+namespace Apoloz\AlfaBank\Sbp\Data;
+
+// <SECTION name="module_imports" intent="Import the base Spatie\LaravelData class.">
+// <BELIEF_STATE "This class extends `Spatie\LaravelData\Data` to leverage its robust data mapping and type safety, ensuring consistent and predictable handling of SBP QR Code response payloads.">
+use Spatie\LaravelData\Data;
+
+// </SECTION>
+/**
+*
+*    "queryData":
+        {
+            "notificationUrl":"https://sbp-payments",
+            "SenderFIO":"Иванов|Иван|Иванович",
+            "SenderID":"0079123456789",
+            "SenderBankBIC":"44525593"
+        }
+*
+* */
+// <SECTION name="class_definition" intent="Define the QR Code response data structure.">
+// <BELIEF_STATE "The `QrCodeResponseData` DTO encapsulates all possible fields returned by the SBP QR Code generation API. Fields are explicitly typed as nullable to accommodate variations in API responses, particularly for error scenarios where certain data might be absent.">
+class GetQRCdQueryData extends Data
+{
+    public function __construct(
+        public string $notificationUrl,
+        public string $SenderFIO,
+        public string $SenderID
+    ) {}
+}
--- a/src/Sbp/Data/QrCodeRequestData.php
+++ b/src/Sbp/Data/QrCodeRequestData.php
@@ -54,8 +54,8 @@ class QrCodeRequestData extends Data
        public ?string $width = null,
        public ?string $height = null,

-        // <BELIEF_STATE "The `notificationUrl` specifies where the bank should send webhook notifications about payment status changes.">
-        public ?string $notificationUrl = null,
+        // <BELIEF_STATE "The `queryData` specifies where the bank should send webhook notifications about payment status changes.">
+        public GetQRCdQueryData $queryData,

        // Dynamic QR specific fields
        // <BELIEF_STATE "The `OrderNumber` is specific to dynamic QRs, providing a unique identifier for the order in the merchant's system.">
@@ -68,17 +68,6 @@ class QrCodeRequestData extends Data
        // <BELIEF_STATE "Subscription service identifiers are used for recurring payment scenarios with SBP.">
        public ?string $subscriptionServiceId = null,
        public ?string $subscriptionServiceName = null,
-
-        // Optional user data for Dynamic QR (often part of sender identification)
-        // <BELIEF_STATE "Sender details are crucial for identifying the payer in certain SBP scenarios. `#[MapName]` ensures these follow API conventions.">
-        #[MapName('SenderFIO')]
-        public ?string $senderFio = null,
-
-        #[MapName('SenderID')]
-        public ?string $senderId = null,
-
-        #[MapName('SenderBankBIC')]
-        public ?string $senderBankBic = null,
    ) {}
    // </SECTION>
 }
--- a/src/Traits/HasAlfaErrorHandling.php
+++ b/src/Traits/HasAlfaErrorHandling.php
@@ -43,7 +43,8 @@ trait HasAlfaErrorHandling
        if (str_contains($contentType, 'application/json')) {
            $data = $response->json();
            $errorCode = $data['error'] ?? $data['ErrorCode'] ?? 'HTTP_' . $response->status();
-            $errorDescription = $data['error_description'] ?? $data['message'] ?? 'Request failed';
+            $rawDescription = $data['error_description'] ?? $data['message'] ?? 'Request failed';
+            $errorDescription = $this->decodeBankMessage($rawDescription);
        } else {
            $errorCode = 'HTTP_' . $response->status();
            $errorDescription = 'Request failed with status ' . $response->status();
@@ -55,4 +56,15 @@ trait HasAlfaErrorHandling
            "({$requestId}) {$errorDescription}"
        );
    }
+
+    private function decodeBankMessage(string $message): string
+    {
+        $decoded = preg_replace_callback(
+            '/%u([0-9A-Fa-f]{4})/',
+            fn ($m) => mb_convert_encoding(pack('H*', $m[1]), 'UTF-8', 'UCS-2BE'),
+            $message
+        );
+
+        return urldecode($decoded);
+    }
 }
Author	SHA1	Message	Date
Anatoliy Poloz	9b62a59705	saloon update	2026-04-25 13:59:25 +03:00
Anatoliy Poloz	d4db68f2e7	refactor(error): handling	2026-04-07 18:47:53 +03:00
Anatoliy Poloz	ea374d2696	doc(test-payin) added	2026-04-07 18:44:27 +03:00
Anatoliy Poloz	13c91ad108	bump versions	2026-04-05 09:37:54 +03:00
Anatoliy Poloz	3cf15b7913	refactor(qr)	2026-04-02 16:45:41 +03:00