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