diff --git a/README.md b/README.md index dc33e84..66f97de 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,5 @@ # Alfa Bank SDK (Unofficial) -[![Tests](https://github.com/apoloz/alfa-bank-sdk/actions/workflows/tests.yml/badge.svg)](https://github.com/apoloz/alfa-bank-sdk/actions) -[![Static Analysis](https://img.shields.io/badge/phpstan-level%205-brightgreen.svg)](https://phpstan.org/) - Профессиональная PHP-библиотека для интеграции с API Альфа-Банка (BaaS и СБП). Построена на базе [Saloon v3](https://docs.saloon.dev) и [Spatie Laravel Data](https://spatie.be/docs/laravel-data). ## Требования @@ -23,6 +20,7 @@ composer require apoloz/alfa-bank-sdk **1. Генерация закрытого ключа и запроса (CSR):** Используйте OpenSSL для создания ключа и файла запроса. Создайте файл `openssl.cnf`: + ```ini [req] distinguished_name = req_distinguished_name @@ -37,6 +35,7 @@ emailAddress = your_email@company.com ``` Выполните команды в терминале: + ```bash # Генерация закрытого ключа (храните его в секрете!) openssl genrsa -out private.key 2048 @@ -54,6 +53,7 @@ openssl req -new -key private.key -out request.csr -config openssl.cnf -utf8 ## Конфигурация (Laravel) Опубликуйте файл конфигурации: + ```bash php artisan vendor:publish --tag=alfa-bank-config ``` @@ -123,16 +123,19 @@ SDK поддерживает две разные модели безопасно ### 1. Подключение к СБП (Pay-in) **Шаги для получения доступа:** + 1. Генерируете пару ключей: `openssl req -x509 -newkey rsa:2048 -keyout client.key -out client.crt -nodes -days 3650`. 2. Отправляете `client.crt` менеджеру банка (acquiring@alfabank.ru). 3. Получаете от банка `alias` (key-name) и `TermNo`. **Поток данных и подпись:** -* **Transport**: Обязательный **MTLS**. Вы должны передать `client.crt` и `client.key` в конфигурацию Guzzle/Saloon. -* **Payload**: Тело запроса канонизируется по алгоритму **JCS**. -* **Signature**: SHA256withRSA подпись JCS-строки помещается в заголовок `Authorization`. + +- **Transport**: Обязательный **MTLS**. Вы должны передать `client.crt` и `client.key` в конфигурацию Guzzle/Saloon. +- **Payload**: Тело запроса канонизируется по алгоритму **JCS**. +- **Signature**: SHA256withRSA подпись JCS-строки помещается в заголовок `Authorization`. **SDK делает это автоматически**: + ```php // В config/alfa-bank.php 'sbp' => [ @@ -147,15 +150,18 @@ SDK поддерживает две разные модели безопасно ### 2. Подключение к BaaS (Номинальные счета) **Шаги для получения доступа:** + 1. Регистрация в личном кабинете партнера. 2. Получение `client_id` и `client_secret` для OAuth2. 3. Регистрация публичного ключа для проверки подписей выплат. **Поток данных и подпись:** -* **Auth**: Стандартный OAuth2 Bearer Token. -* **Payload Signature**: Для критических операций (выплаты, идентификация) требуется `digestSignatures`. Это массив CMS-подписей (PKCS7) в формате Base64, которыми подписываются финансовые поля. + +- **Auth**: Стандартный OAuth2 Bearer Token. +- **Payload Signature**: Для критических операций (выплаты, идентификация) требуется `digestSignatures`. Это массив CMS-подписей (PKCS7) в формате Base64, которыми подписываются финансовые поля. **Пример формирования CMS в SDK:** + ```php use Apoloz\AlfaBank\Utils\CmsSigner; @@ -170,6 +176,7 @@ $signature = CmsSigner::sign($payload, $privateKey, $certificate); SDK использует нативный функционал Saloon для OAuth2. **1. Инициализация:** + ```php $baas = AlfaBank::baas( clientId: '...', clientSecret: '...', redirectUri: '...', @@ -178,12 +185,14 @@ $baas = AlfaBank::baas( ``` **2. Получение ссылки на вход:** + ```php $url = $baas->getAuthorizationUrl(['beneficiaries']); // Перенаправьте пользователя на $url ``` **3. Обмен кода на токен:** + ```php $authenticator = $baas->getAccessToken($code); $baas->authenticate($authenticator); // Применить токен @@ -191,6 +200,7 @@ $baas->authenticate($authenticator); // Применить токен ``` **4. Обновление токена:** + ```php $newAuth = $baas->refreshAccessToken($savedRefreshToken); $baas->authenticate($newAuth); @@ -199,7 +209,9 @@ $baas->authenticate($newAuth); Полный пример: [examples/13_h2h_auth_service.php](examples/13_h2h_auth_service.php) ### 4. Генерация Client Secret (Утилита) + Если банк выдал только сертификаты, вы можете сгенерировать `client_secret` самостоятельно: + ```php // См. examples/14_generate_client_secret.php $baas->send(new RefreshClientSecretRequest($clientId)); @@ -215,6 +227,7 @@ $baas->send(new RefreshClientSecretRequest($clientId)); ## Архитектура и Потоки данных ### Гибридный поток: СБП -> Номинальный счет + ```mermaid sequenceDiagram participant Client as Покупатель @@ -229,7 +242,7 @@ sequenceDiagram Note over API, BaaS: Webhook with Signature API->>BaaS: 4. Webhook (Входящий платеж) - + Note over BaaS, API: OAuth2 + CMS Signature BaaS->>API: 5. IdentifyTransactionRequest(beneficiaryId) API-->>BaaS: 6. 200 OK (Зачислено) @@ -240,6 +253,7 @@ sequenceDiagram ## Примеры использования ### 1. СБП: Прием платежа на номинальный счет + ```php use Apoloz\AlfaBank\Laravel\Facades\Sbp; use Apoloz\AlfaBank\Sbp\Requests\GetQrCodeRequest; @@ -257,6 +271,7 @@ echo "QR URL: " . $response->dto()->payload; ``` ### 2. Идентификация платежа (BaaS) + Когда платеж пришел на номинальный счет, его нужно привязать к бенефициару: ```php @@ -279,9 +294,11 @@ AlfaBank::send(new IdentifyTransactionRequest($data)); ``` ### 3. Работа с номинальными счетами (Бенефициары) + ... (existing content) ... ### 4. Самозанятые (Регистрация доходов) + ```php use Apoloz\AlfaBank\Requests\SelfEmployed\RegisterIncomeRequest; use Apoloz\AlfaBank\Data\SelfEmployed\CreateIncomeRequestData; @@ -297,7 +314,9 @@ $response = AlfaBank::send(new RegisterIncomeRequest($data)); ``` ### 5. Файловый обмен (KYC) + Загрузка сканов документов бенефициаров через pre-signed ссылки: + ```php use Apoloz\AlfaBank\Requests\Files\UploadFileRequest; @@ -311,16 +330,18 @@ AlfaBank::send(new UploadFileRequest($uploadUrl, $file)); Эти примеры разработаны специально для быстрого запуска и тестирования в консоли `php artisan tinker`. Они содержат полные цепочки бизнес-логики. -* [17_laravel_tinker_scoring_creation.php](examples/17_laravel_tinker_scoring_creation.php) — **Скоринг и Создание Бенефициара**: Полный цикл проверки и регистрации контрагента с автоматической подписью данных. -* [18_laravel_tinker_identification_payout.php](examples/18_laravel_tinker_identification_payout.php) — **Идентификация и Выплата**: Привязка входящих денег к бенефициару и последующий вывод на карту (с шифрованием PAN). -* [19_laravel_tinker_card_registration_payout.php](examples/19_laravel_tinker_card_registration_payout.php) — **Безопасная регистрация карт**: Токенизация карты (создание Реквизита) и выплата по ID (PCI DSS Friendly). +- [17_laravel_tinker_scoring_creation.php](examples/17_laravel_tinker_scoring_creation.php) — **Скоринг и Создание Бенефициара**: Полный цикл проверки и регистрации контрагента с автоматической подписью данных. +- [18_laravel_tinker_identification_payout.php](examples/18_laravel_tinker_identification_payout.php) — **Идентификация и Выплата**: Привязка входящих денег к бенефициару и последующий вывод на карту (с шифрованием PAN). +- [19_laravel_tinker_card_registration_payout.php](examples/19_laravel_tinker_card_registration_payout.php) — **Безопасная регистрация карт**: Токенизация карты (создание Реквизита) и выплата по ID (PCI DSS Friendly). --- ## Продвинутые возможности ### Управление возвратами СБП + Просмотр всей истории попыток возврата по транзакции: + ```php $response = Sbp::send(new GetQrcReversalHistoryRequest($payrrn, $termNo)); foreach ($response->dto()->refunds as $refund) { @@ -329,6 +350,7 @@ foreach ($response->dto()->refunds as $refund) { ``` ### Webhook Handling (Laravel) + ```php // Обработка СБП уведомлений в Listener public function handle(AlfaWebhookReceived $event) { @@ -338,7 +360,3 @@ public function handle(AlfaWebhookReceived $event) { } } ``` - -## Лицензия - -MIT. Автор: Anatoliy Poloz.