forked from apoloz/alfa-bank-sdk
146 lines
3.2 KiB
Markdown
146 lines
3.2 KiB
Markdown
# Alfa Bank SDK (Unofficial)
|
|
|
|
This is an unofficial PHP SDK for the [Alfa Bank API](https://developers.alfabank.ru/), built using [Saloon](https://docs.saloon.dev) and [Spatie Laravel Data](https://spatie.be/docs/laravel-data).
|
|
|
|
## Requirements
|
|
|
|
- PHP 8.2+
|
|
- OpenSSL (for certificate generation/handling)
|
|
- [Saloon](https://docs.saloon.dev)
|
|
- [Spatie Laravel Data](https://spatie.be/docs/laravel-data)
|
|
- [phpseclib](https://phpseclib.org/) (for Card Encryption)
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
composer require apoloz/alfa-bank-sdk
|
|
```
|
|
|
|
## Laravel Integration
|
|
|
|
The package supports auto-discovery. Publish the config file:
|
|
|
|
```bash
|
|
php artisan vendor:publish --tag=alfa-bank-config
|
|
```
|
|
|
|
Configure your `.env`:
|
|
```env
|
|
ALFA_BAAS_CERT_PATH=/path/to/cert.cer
|
|
ALFA_BAAS_KEY_PATH=/path/to/key.key
|
|
ALFA_BAAS_ENV=sandbox
|
|
|
|
ALFA_SBP_CERT_PATH=/path/to/cert.cer
|
|
ALFA_SBP_KEY_PATH=/path/to/key.key
|
|
ALFA_SBP_KEY_ALIAS=your-alias
|
|
ALFA_SBP_ENV=sandbox
|
|
```
|
|
|
|
Now you can inject the connectors:
|
|
```php
|
|
use Apoloz\AlfaBank\AlfaBankConnector;
|
|
|
|
public function index(AlfaBankConnector $connector) {
|
|
$connector->withToken('...')->send(new GetNominalAccountsRequest());
|
|
}
|
|
```
|
|
|
|
## Core Usage (Generic PHP)
|
|
|
|
### 1. Initialize the Connector
|
|
|
|
```php
|
|
use Apoloz\AlfaBank\AlfaBankConnector;
|
|
use Apoloz\AlfaBank\Enums\Environment;
|
|
|
|
$connector = new AlfaBankConnector(
|
|
certificatePath: '/path/to/client.cer',
|
|
privateKeyPath: '/path/to/private.key',
|
|
environment: Environment::SANDBOX
|
|
);
|
|
```
|
|
|
|
### 2. Authentication
|
|
|
|
```php
|
|
use Apoloz\AlfaBank\Requests\Auth\GetTokenRequest;
|
|
|
|
$request = new GetTokenRequest(
|
|
clientId: 'your-client-id',
|
|
clientSecret: 'your-client-secret',
|
|
code: 'auth-code',
|
|
redirectUri: 'https://your-app.com/callback'
|
|
);
|
|
|
|
$response = $connector->send($request);
|
|
$tokenData = $response->dto();
|
|
|
|
$connector->withToken($tokenData->access_token);
|
|
```
|
|
|
|
### 3. SBP / QR Payouts (C2B)
|
|
|
|
```php
|
|
use Apoloz\AlfaBank\Sbp\SbpConnector;
|
|
|
|
$sbpConnector = new SbpConnector(
|
|
certificatePath: '/path/to/client.cer',
|
|
privateKeyPath: '/path/to/private.key',
|
|
keyNameAlias: 'your-key-alias',
|
|
environment: Environment::SANDBOX
|
|
);
|
|
|
|
$response = $sbpConnector->send(new GetQrCodeRequest($payload));
|
|
```
|
|
|
|
### 4. Utilities
|
|
|
|
#### Card PAN Encryption
|
|
Required for card payouts in Nominal Accounts.
|
|
|
|
```php
|
|
use Apoloz\AlfaBank\Utils\CardEncryptor;
|
|
|
|
$encryptedPan = CardEncryptor::encrypt(
|
|
pan: '4779642610000010',
|
|
publicKeyPem: file_get_contents('alfa-card-key.pub')
|
|
);
|
|
```
|
|
|
|
#### JSON Web Signature (JWS)
|
|
Used for signing some BaaS requests.
|
|
|
|
```php
|
|
use Apoloz\AlfaBank\Utils\JwsSigner;
|
|
|
|
$jws = JwsSigner::sign(
|
|
payload: ['foo' => 'bar'],
|
|
privateKeyPem: file_get_contents('my-key.pem'),
|
|
certificateSerialNumber: '610003...'
|
|
);
|
|
```
|
|
|
|
#### JSON Web Encryption (JWE)
|
|
Used for encrypting sensitive BaaS requests.
|
|
|
|
```php
|
|
use Apoloz\AlfaBank\Utils\JweEncryptor;
|
|
|
|
$jwe = JweEncryptor::encrypt(
|
|
jws: $jws,
|
|
publicKeyPem: file_get_contents('alfa-cert.cer'),
|
|
certificateSerialNumber: '610003...'
|
|
);
|
|
```
|
|
|
|
## Features
|
|
|
|
- **Mutual TLS**: Automated certificate handling.
|
|
- **Laravel Ready**: Service Provider and Config included.
|
|
- **Typed DTOs**: Comprehensive response parsing.
|
|
- **Full Product Coverage**: BaaS (Nominal Accounts, Escrow), SBP (QR, Subscriptions), Digital Ruble.
|
|
|
|
## License
|
|
|
|
MIT
|