Hasan/alfa-bank-sdk
1
0
Fork 0
forked from apoloz/alfa-bank-sdk
Code Pull Requests Activity

docs(readme): updated

Browse Source
This commit is contained in:
Анатолий Полоз
2026-01-26 12:59:26 +03:00
parent e23e2ea6df
commit e83bb5e7e7
1 changed files with 10 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
README.md
View File

@@ -20,7 +20,6 @@ composer require apoloz/alfa-bank-sdk
**1. Генерация закрытого ключа и запроса (CSR):**
Используйте OpenSSL для создания ключа и файла запроса. Создайте файл `openssl.cnf`:
```ini
[req]
distinguished_name = req_distinguished_name
@@ -35,7 +34,6 @@ emailAddress = your_email@company.com
```
Выполните команды в терминале:
```bash
# Генерация закрытого ключа (храните его в секрете!)
openssl genrsa -out private.key 2048
@@ -53,7 +51,6 @@ openssl req -new -key private.key -out request.csr -config openssl.cnf -utf8
## Конфигурация (Laravel)
Опубликуйте файл конфигурации:
```bash
php artisan vendor:publish --tag=alfa-bank-config
```
@@ -123,19 +120,16 @@ 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' => [
@@ -150,18 +144,15 @@ 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;
@@ -176,7 +167,6 @@ $signature = CmsSigner::sign($payload, $privateKey, $certificate);
SDK использует нативный функционал Saloon для OAuth2.
**1. Инициализация:**
```php
$baas = AlfaBank::baas(
clientId: '...', clientSecret: '...', redirectUri: '...',
@@ -185,14 +175,12 @@ $baas = AlfaBank::baas(
```
**2. Получение ссылки на вход:**
```php
$url = $baas->getAuthorizationUrl(['beneficiaries']);
// Перенаправьте пользователя на $url
```
**3. Обмен кода на токен:**
```php
$authenticator = $baas->getAccessToken($code);
$baas->authenticate($authenticator); // Применить токен
@@ -200,7 +188,6 @@ $baas->authenticate($authenticator); // Применить токен
```
**4. Обновление токена:**
```php
$newAuth = $baas->refreshAccessToken($savedRefreshToken);
$baas->authenticate($newAuth);
@@ -209,9 +196,7 @@ $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));
@@ -227,7 +212,6 @@ $baas->send(new RefreshClientSecretRequest($clientId));
## Архитектура и Потоки данных
### Гибридный поток: СБП -> Номинальный счет
```mermaid
sequenceDiagram
participant Client as Покупатель
@@ -242,7 +226,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 (Зачислено)
@@ -253,7 +237,6 @@ sequenceDiagram
## Примеры использования
### 1. СБП: Прием платежа на номинальный счет
```php
use Apoloz\AlfaBank\Laravel\Facades\Sbp;
use Apoloz\AlfaBank\Sbp\Requests\GetQrCodeRequest;
@@ -271,7 +254,6 @@ echo "QR URL: " . $response->dto()->payload;
```
### 2. Идентификация платежа (BaaS)
Когда платеж пришел на номинальный счет, его нужно привязать к бенефициару:
```php
@@ -294,11 +276,9 @@ AlfaBank::send(new IdentifyTransactionRequest($data));
```
### 3. Работа с номинальными счетами (Бенефициары)
... (existing content) ...
### 4. Самозанятые (Регистрация доходов)
```php
use Apoloz\AlfaBank\Requests\SelfEmployed\RegisterIncomeRequest;
use Apoloz\AlfaBank\Data\SelfEmployed\CreateIncomeRequestData;
@@ -314,9 +294,7 @@ $response = AlfaBank::send(new RegisterIncomeRequest($data));
```
### 5. Файловый обмен (KYC)
Загрузка сканов документов бенефициаров через pre-signed ссылки:
```php
use Apoloz\AlfaBank\Requests\Files\UploadFileRequest;
@@ -330,18 +308,16 @@ 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) {
@@ -350,7 +326,6 @@ foreach ($response->dto()->refunds as $refund) {
```
### Webhook Handling (Laravel)
```php
// Обработка СБП уведомлений в Listener
public function handle(AlfaWebhookReceived $event) {
@@ -360,3 +335,4 @@ public function handle(AlfaWebhookReceived $event) {
}
}
```