Alfa Bank SDK (Unofficial)

Профессиональная PHP-библиотека для интеграции с API Альфа-Банка (BaaS и СБП). Построена на базе Saloon v3 и Spatie Laravel Data.

Требования

• PHP 8.2+
• Расширение OpenSSL
• Saloon v3.0+
• Spatie Laravel Data

Установка

composer require apoloz/alfa-bank-sdk

---

Архитектура и потоки данных

Библиотека обеспечивает строгую типизацию на всех этапах. Вы работаете только с объектами (DTO), а SDK берет на себя всю сложность протоколов банка.

1. Жизненный цикл запроса (BaaS)

sequenceDiagram
    participant App as Приложение
    participant DTO as Request DTO
    participant SDK as Connector
    participant API as Alfa Bank

    App->>DTO: 1. Создание данных
    App->>SDK: 2. send(Request)
    SDK->>SDK: 3. Маппинг полей (PascalCase)
    SDK->>SDK: 4. Подпись/Шифрование
    SDK->>API: 5. HTTPS + mTLS
    API-->>SDK: 6. JSON Ответ
    SDK->>SDK: 7. Валидация ошибок
    SDK->>App: 8. Возврат Response DTO

2. Безопасность СБП (Body Signing)

Для СБП реализована автоматическая каноникализация JSON (JCS) с рекурсивной сортировкой ключей перед подписью RSA-SHA256.

---

Настройка и Безопасность

Альфа-Банк требует два набора ключей:

1. Транспортные (mTLS): Для установки защищенного соединения.
2. Прикладные (Signing): Для цифровой подписи реестров и платежей.

Быстрый старт (Laravel)

1. Опубликуйте конфиг:

php artisan vendor:publish --tag=alfa-bank-config

2. Настройте .env:

ALFA_BAAS_CERT_PATH=/path/to/transport.crt
ALFA_BAAS_KEY_PATH=/path/to/transport.key
ALFA_BAAS_CLIENT_ID=your_id
ALFA_BAAS_CLIENT_SECRET=your_secret

3. Проверьте соединение:

php artisan alfa:check

---

Примеры использования

1. Авторизация и получение счетов

use Apoloz\AlfaBank\Laravel\Facades\AlfaBank;
use Apoloz\AlfaBank\Requests\Accounts\GetAccountsRequest;

// SDK сам получит токен и применит его
$accounts = AlfaBank::send(new GetAccountsRequest());

foreach ($accounts as $account) {
    echo $account->number . ": " . $account->openDate;
}

2. Стандартный платеж (BaaS)

use Apoloz\AlfaBank\Requests\Payments\CreatePaymentRequest;
use Apoloz\AlfaBank\Data\Payments\PaymentData;

$data = new PaymentData(
    amount: 1500.00,
    date: date('Y-m-d'),
    externalId: 'INV-2026-001',
    operationCode: '01',
    payeeAccount: '40702...',
    payeeBankBic: '044525593',
    payeeName: 'ООО Партнер',
    payerAccount: '40702...',
    payerBankBic: '044525593',
    payerBankCorrAccount: '30101...',
    payerInn: '7700000000',
    payerName: 'Моя Компания',
    priority: '5',
    purpose: 'Оплата по счету №1'
);

$response = AlfaBank::send(new CreatePaymentRequest($data));
echo "Платеж создан: " . $response->id;

3. СБП: Генерация QR-кода

use Apoloz\AlfaBank\Laravel\Facades\Sbp;
use Apoloz\AlfaBank\Sbp\Requests\GetQrCodeRequest;
use Apoloz\AlfaBank\Sbp\Data\QrCodeRequestData;

$payload = new QrCodeRequestData(
    termNo: '90080567',
    amount: '10000', // 100.00 руб
    paymentPurpose: 'Заказ №5'
);

$response = Sbp::send(new GetQrCodeRequest($payload));
echo "Отсканируйте код: " . $response->payload;

4. Работа с выписками (Пагинация)

use Apoloz\AlfaBank\Requests\Statement\GetTransactionsRequest;

// Автоматическая итерация через все страницы
$paginator = AlfaBank::paginate(new GetTransactionsRequest(
    accountNumber: '40702...',
    executeDateFrom: '2026-01-01',
    executeDateTo: '2026-01-18'
));

foreach ($paginator->items() as $transaction) {
    echo "Транзакция {" . $transaction->uuid . ": " . $transaction->amount['amount'] . " RUB\n";
}

5. Самозанятые (Справочники и выплаты)

use Apoloz\AlfaBank\Requests\SelfEmployed\GetActivitiesRequest;

// Получение списка разрешенных видов деятельности
$activities = AlfaBank::send(new GetActivitiesRequest());

foreach ($activities as $activity) {
    echo "{$activity->code}: {$activity->name}\n";
}

6. Номинальные счета (Полный цикл)

Сценарий создания бенефициара и выплаты с подписью:

use Apoloz\AlfaBank\Requests\NominalAccounts\Beneficiaries\CreateBeneficiaryRequest;
use Apoloz\AlfaBank\Requests\NominalAccounts\Payouts\CreatePayoffRequest;

// 1. Создание бенефициара с CMS подписью
$response = $baas->send(new CreateBeneficiaryRequest($beneficiaryData));

// 2. Инициирование выплаты
$payoff = $baas->send(new CreatePayoffRequest($payoffData));
echo "Статус выплаты: " . $payoff->dto()->status;

---

Продвинутые возможности

Диагностика без Laravel

use Apoloz\AlfaBank\AlfaBank;

$ok = AlfaBank::check(
    certificatePath: 'cert.pem',
    privateKeyPath: 'key.pem',
    clientId: '...',
    clientSecret: '...'
);

Логирование с маскировкой данных

SDK автоматически скрывает номера карт, токены и подписи в логах.

$connector = AlfaBank::getFacadeRoot();
$connector->withLogging(Log::channel('daily')->getLogger());

Обработка Webhooks (Laravel)

// routes/api.php
Route::alfaWebhooks('/webhooks/alfa');

// Listener
public function handle(AlfaWebhookReceived $event) {
    $data = $event->webhook->data; 
    // $data будет объектом TransactionWebhookData или SbpPaymentWebhookData
}

---

Лицензия

MIT. Автор: Anatoliy Poloz.