Hasan/alfa-bank-sdk
1
0
Fork 0
forked from apoloz/alfa-bank-sdk
Code Pull Requests Activity
Files
d214eecebe106c87bd4f6e9df15a71b9fdabafe7
alfa-bank-sdk/README.md

557 lines
14 KiB
Markdown
Raw Blame History

# 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) v3.0+
- [Spatie Laravel Data](https://spatie.be/docs/laravel-data)
- [phpseclib](https://phpseclib.org/) (for Card Encryption)
## Installation
```bash
composer require apoloz/alfa-bank-sdk
```
## Security & Setup (Crucial)
Alfa Bank uses a comprehensive security model requiring **two distinct sets of keys**:
1. **Transport (mTLS):** To establish the SSL connection.
2. **Signing (JWS/CMS):** To digitally sign the request body.
### Where to get keys?
- **Sandbox:** Provided by the bank support or downloaded from the Developer Portal (usually as `.pfx` or `.zip`).
- **Production:**
- **Transport (mTLS):** Generate a private key and CSR using OpenSSL (`openssl genrsa`, `openssl req`). Send the CSR to `alfa_api@alfabank.ru`. The bank will reply with your Certificate.
- **Signing:** Generated by you (the client). The public certificate must be registered in "Alfa Business Online" or sent to your onboarding manager.
### 1. Converting PFX to PEM
If the bank provided a `.pfx` file for signing, you must convert it to PEM format:
```bash
# Extract Private Key
openssl pkcs12 -in signing.pfx -nocerts -out signing_key.pem -nodes
# Extract Public Certificate
openssl pkcs12 -in signing.pfx -clcerts -nokeys -out signing_cert.pem
```
### 2. Initialization
You can now initialize the SDK with both key pairs:
```php
use Apoloz\AlfaBank\AlfaBank;
use Apoloz\AlfaBank\Enums\Environment;
$baas = AlfaBank::baas(
// Transport Keys (mTLS)
certificatePath: '/path/to/transport_cert.pem',
privateKeyPath: '/path/to/transport_key.pem',
// Signing Keys (Business Logic) - Optional, defaults to transport keys if not set
signingCertificatePath: '/path/to/signing_cert.pem',
signingPrivateKeyPath: '/path/to/signing_key.pem',
environment: Environment::SANDBOX,
caBundlePath: '/path/to/root_ca_bundle.crt'
);
```
## Core Usage
### Authentication (BaaS)
Use the `login` method to perform OAuth Client Credentials flow:
```php
$baas->login(
clientId: 'your-client-id',
clientSecret: 'your-client-secret'
);
```
### Making Requests
#### SBP: Generate QR Code
```php
use Apoloz\AlfaBank\Sbp\Requests\GetQrCodeRequest;
use Apoloz\AlfaBank\Sbp\Data\QrCodeRequestData;
$sbp = AlfaBank::sbp(
certificatePath: '...',
privateKeyPath: '...',
keyNameAlias: '9728109955', // Terminal ID
signingPrivateKeyPath: '/path/to/signing_key.pem' // Specific signing key for SBP body
);
$response = $sbp->send(new GetQrCodeRequest(
new QrCodeRequestData(TermNo: '...', amount: '100')
));
$link = $response->dto()->payload;
```
#### Nominal Accounts
```php
$response = $baas->send(new CreateBeneficiaryRequest($payload));
```
### Self-Employed (Payouts & Status)
The SDK supports managing self-employed beneficiaries, checking their FTS status, and processing payouts.
#### Check Taxpayer Status
```php
use Apoloz\AlfaBank\Requests\SelfEmployed\GetTaxpayerStatusRequest;
use Apoloz\AlfaBank\Data\SelfEmployed\TaxpayerStatusRequestData;
$payload = new TaxpayerStatusRequestData(
externalId: 'unique-id',
selfemployedVatinList: ['123456789012']
);
$response = $baas->send(new GetTaxpayerStatusRequest($payload));
$status = $response->dto()->taxpayerStatusList[0];
```
#### Process Payout
```php
use Apoloz\AlfaBank\Requests\SelfEmployed\CreatePayoutRequest;
use Apoloz\AlfaBank\Data\SelfEmployed\PayoutRequestData;
$payload = new PayoutRequestData(
externalId: 'ext-id-456',
company: ['vatin' => '7700000000'],
requisite: [
['amount' => 1000, 'vatin' => '112233445566']
]
);
$response = $baas->send(new CreatePayoutRequest($payload));
```
### File Exchange
Upload and download files securely.
```php
use Apoloz\AlfaBank\Requests\FileExchange\UploadFileRequest;
use Apoloz\AlfaBank\Requests\FileExchange\DownloadFileRequest;
// Upload
$stream = fopen('path/to/file', 'r');
$baas->send(new UploadFileRequest($uploadUrl, $stream, $fileSize));
// Download
$response = $baas->send(new DownloadFileRequest($downloadUrl));
$content = $response->body();
```
### Payments (RUR Payment Orders)
Create standard payment orders and check their status.
```php
use Apoloz\AlfaBank\Requests\Payments\CreatePaymentRequest;
use Apoloz\AlfaBank\Data\Payments\PaymentData;
$payload = new PaymentData(
amount: 100.50,
date: '2023-10-25',
externalId: 'order-12345',
operationCode: '01',
payeeAccount: '40702...',
payeeBankBic: '044525225',
payeeName: 'Partner LLC',
payerAccount: '40702...',
payerBankBic: '044525593',
payerBankCorrAccount: '30101...',
payerInn: '7700000000',
payerName: 'My Company',
priority: '5',
purpose: 'Payment for services'
);
// Create Payment
$baas->send(new CreatePaymentRequest($payload));
// Check State
use Apoloz\AlfaBank\Requests\Payments\GetPaymentStateRequest;
$state = $baas->send(new GetPaymentStateRequest('order-12345'))->dto();
echo $state->bankStatus; // e.g. ACCEPTED
```
### Cards
Retrieve a list of client cards.
```php
use Apoloz\AlfaBank\Requests\Cards\GetCardsRequest;
$response = $baas->send(new GetCardsRequest());
foreach ($response->dto() as $card) {
echo $card->maskedNumber . ' - ' . $card->status;
}
```
### B2C Payouts (SBP via Phone)
Send money to individuals using their phone number through SBP.
```php
use Apoloz\AlfaBank\Requests\B2C\CreateB2CPaymentRequest;
use Apoloz\AlfaBank\Data\B2C\B2CPaymentRequestData;
use Apoloz\AlfaBank\Data\B2C\B2CClientData;
use Apoloz\AlfaBank\Data\B2C\B2CPaymentRecipientData;
$payload = new B2CPaymentRequestData(
client: new B2CClientData(b2cClientId: '...', partnerId: 123),
inn: '7700000000',
account: '40702...',
total: 100.53,
signedBody: '...base64_signature...',
payments: B2CPaymentRecipientData::collect([
[
'phone' => '79001112233',
'amount' => 100.53,
'nspkBankId' => '100000000001',
'sequence' => 'unique-seq-1',
'name' => ['first' => 'Ivan', 'last' => 'Ivanov']
]
], DataCollection::class)
);
$baas->send(new CreateB2CPaymentRequest($payload));
```
### Payment Registries (Batch Ruble Payments)
Create a registry for multiple ruble payments and sign it.
```php
use Apoloz\AlfaBank\Requests\Registries\CreateRegistryRequest;
use Apoloz\AlfaBank\Data\Registries\RegistryRequestData;
use Apoloz\AlfaBank\Data\Registries\RegistryPaymentData;
$payload = new RegistryRequestData(
payments: RegistryPaymentData::collect([
[
'amount' => 1000.0,
'date' => '2023-11-01',
'payeeAccount' => '40702...',
'payeeBankBic' => '044525225',
'payeeInn' => '7700000000',
'payeeName' => 'Vendor LLC',
'payerAccount' => '40702...',
'purpose' => 'Batch payment part 1'
]
], DataCollection::class),
description: 'Weekly payroll'
);
$response = $baas->send(new CreateRegistryRequest($payload));
$registryId = $response->json('id');
// Sign Registry
use Apoloz\AlfaBank\Requests\Registries\SignRegistryRequest;
use Apoloz\AlfaBank\Data\Registries\RegistrySignatureData;
use Spatie\LaravelData\DataCollection;
$signatures = RegistrySignatureData::collect([
[
'base64Encoded' => '...', // Base64 signature
'signatureType' => 'RSA',
'certificateUuid' => '...'
]
], DataCollection::class);
$baas->send(new SignRegistryRequest($registryId, $signatures));
```
### Customer Info
Get organization profile.
```php
use Apoloz\AlfaBank\Requests\CustomerInfo\GetCustomerInfoRequest;
$info = $baas->send(new GetCustomerInfoRequest())->dto();
echo $info->fullName;
```
### Limits
Get client's operation limits.
```php
use Apoloz\AlfaBank\Requests\Limits\GetGeneralLimitsRequest;
$response = $baas->send(new GetGeneralLimitsRequest());
$limits = $response->json();
```
### Debit Cards
Apply for a new debit card.
```php
use Apoloz\AlfaBank\Requests\DebitCards\CreateDebitCardApplicationRequest;
use Apoloz\AlfaBank\Data\DebitCards\DebitCardApplicationData;
$payload = new DebitCardApplicationData(
embossingName: 'IVAN IVANOV',
firstName: 'Иван',
lastName: 'Иванов',
middleName: 'Иванович',
mobilePhone: '79001112233',
passportBirthDate: '1990-01-01',
sex: 'm',
sopdConfirmed: true
);
$baas->send(new CreateDebitCardApplicationRequest($payload));
```
### User Compliance
Check user compliance for loans.
```php
use Apoloz\AlfaBank\Requests\Compliance\GetUserComplianceRequest;
$baas->send(new GetUserComplianceRequest());
```
### DFA (Digital Financial Assets)
List initial placements.
```php
use Apoloz\AlfaBank\Requests\DFA\GetDfaInitialPlacementListRequest;
$baas->send(new GetDfaInitialPlacementListRequest(limit: 5));
```
### Currency Rates
Get currency rates by office.
```php
use Apoloz\AlfaBank\Requests\Rates\GetOfficeRatesRequest;
$baas->send(new GetOfficeRatesRequest());
```
### Escrow Accounts
Manage construction projects and escrow orders.
```php
use Apoloz\AlfaBank\Requests\Escrow\GetBuildProjectsRequest;
$projects = $baas->send(new GetBuildProjectsRequest())->json();
```
### Power of Attorney (Poa)
Request and check status of digital POAs.
```php
use Apoloz\AlfaBank\Requests\Poa\CreatePoaRequest;
$response = $baas->send(new CreatePoaRequest('poa-123', '7700000000'));
$uuid = $response->json('requestUuid');
```
### Loyalty
Access bonus accounts and transaction history.
```php
use Apoloz\AlfaBank\Requests\Loyalty\GetLoyaltyAccountsRequest;
$accounts = $baas->send(new GetLoyaltyAccountsRequest())->json();
```
### Reports
Order certificates and reports.
```php
use Apoloz\AlfaBank\Requests\Reports\CreateAccountBalanceReportRequest;
$baas->send(new CreateAccountBalanceReportRequest(['40702...'], 'eng'));
```
### Crypto Service
Manage encryption and signing certificates.
```php
use Apoloz\AlfaBank\Requests\Crypto\GetCertificatesRequest;
$certificates = $baas->send(new GetCertificatesRequest())->json();
```
### Partner (MMB)
Access partner program data and applications.
```php
use Apoloz\AlfaBank\Requests\Partner\GetPartnerApplicationsRequest;
$apps = $baas->send(new GetPartnerApplicationsRequest())->json();
```
### Miscellaneous
- **Bonus Numbers**: `$baas->send(new GetBonusNumbersRequest());`
- **Credit Offers**: `$baas->send(new GetCreditOffersRequest());`
- **Self-encashment**: `$baas->send(new CreateSelfEncashmentRegistryRequest($data));`
- **Business Lounge**: `$baas->send(new GetLoungeBalanceRequest());`
- **Scoring**: `$baas->send(new GetComplianceScoreRequest('7700000000'));`
- **Security**: `$baas->send(new GetSubscriptionsRequest());`
- **Logistics**: `$baas->send(new GetDeliveriesRequest('...'));`
- **Webhooks**: `$baas->send(new GetWebhooksRequest());`
- **1C Integration**: `$baas->send(new CheckMerchantRequest('MF123', 'Basic ...'));`
- **Claims**: `$baas->send(new ResolveClaimRequest('ID', $data));`
- **Orders (Travel/Afisha)**: `$baas->send(new CreateTravelOrderRequest($data));`
- **Salary Project**: `$baas->send(new CreatePayrollApplicationRequest($payload));`
- **Cloud Signature**: `$baas->send(new SubmitSigningRequest('REQ-ID'));`
- **Aff Integration**: `$baas->send(new CheckComplianceRequest('INN', 'Name'));`
- **Digital Ruble**: `$sbp->send(new CreateUniQrRequest($uniQrData));`
### Signing Data (CMS)
For requests requiring a digital signature (e.g., Payments), you must canonicalize and sign the data manually.
```php
use Apoloz\AlfaBank\Utils\CmsSigner;
use Apoloz\AlfaBank\Data\NominalAccounts\Payouts\DigestSignatureData;
use Spatie\LaravelData\DataCollection;
// 1. Prepare data
$fields = [
'amount' => 100.50,
// ... other fields
];
// 2. Canonicalize & Sign
$json = CmsSigner::canonicalize($fields);
$cert = file_get_contents('/path/to/signing_cert.pem');
$key = file_get_contents('/path/to/signing_key.pem');
$signature = CmsSigner::sign($json, $cert, $key);
// 3. Attach to DTO
$paymentData->digestSignatures = DigestSignatureData::collect([
[
'base64Encoded' => $signature,
'signatureType' => 'CMS'
]
], DataCollection::class);
```
## Advanced Features
### Pagination
The SDK supports automatic pagination for list endpoints:
```php
use Apoloz\AlfaBank\Requests\Accounts\GetAccountsRequest;
$paginator = $baas->paginate(new GetAccountsRequest());
foreach ($paginator as $account) {
// Each item is processed automatically
}
```
## 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/transport_cert.pem
# ... other settings
ALFA_WEBHOOK_USER=your_webhook_user
ALFA_WEBHOOK_PASSWORD=your_webhook_password
```
### Webhook Handling (Laravel)
The SDK provides a built-in controller and route macro to handle incoming webhooks and dispatch Laravel events.
1. **Register the route** in `routes/api.php`:
```php
Route::alfaWebhooks('/webhooks/alfa');
```
2. **Listen for the event** in `app/Providers/EventServiceProvider.php`:
```php
use Apoloz\AlfaBank\Laravel\Events\AlfaWebhookReceived;
protected $listen = [
AlfaWebhookReceived::class => [
\App\Listeners\HandleAlfaWebhook::class,
],
];
```
3. **Handle the DTO** in your listener:
```php
public function handle(AlfaWebhookReceived $event)
{
$webhook = $event->webhook; // BaseWebhookData DTO
if ($webhook->object === 'ul_transaction_default') {
$transaction = $webhook->data;
// ...
}
}
```
## Error Handling
The SDK throws `Apoloz\AlfaBank\Exceptions\AlfaBankException` when the API returns an error.
```php
try {
$baas->send($request);
} catch (\Apoloz\AlfaBank\Exceptions\AlfaBankException $e) {
echo $e->getErrorCode(); // e.g. "invalid_token" or "RQ05014"
echo $e->getMessage();
}
```
## Utilities
- **Card PAN Encryption**: `CardEncryptor::encrypt($pan, $pubKey)`
- **CMS Signing**: `CmsSigner::sign($data, $cert, $key)`
- **JWS/JWE**: `JwsSigner` and `JweEncryptor` for transport security.
## Diagnostics
### Health Check (Laravel)
Run the built-in Artisan command to verify your mTLS certificates and connection:
```bash
php artisan alfa:check
```
### Logging
Attach a PSR-3 logger to debug requests (sensitive data redacted):
```php
$baas->withLogging(Log::getLogger());
```
## License
MIT
View Git Blame Copy Permalink