alfa-bank-sdk/README_FULL_GUIDE.md

Alfa Bank SDK: The Comprehensive Guide

1. Introduction

This SDK provides a unified, strictly-typed PHP interface for the Alfa Bank API. It covers both Bank-as-a-Service (BaaS) and Faster Payments System (SBP) protocols.

Key Technologies:

• Saloon v3: Handles HTTP transport, retries, and plugins.
• Spatie Laravel Data: Provides Data Transfer Objects (DTOs) for strict typing.
• OpenSSL: Manages GOST/RSA signatures and encryption.

---

2. Installation & Configuration

2.1 Install via Composer

composer require apoloz/alfa-bank-sdk

2.2 Laravel Setup

Publish the configuration file:

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

Configure your .env file. Crucially, you need separate keys for Transport (mTLS) and Signing (Business Logic).

# 1. Transport Security (mTLS) - Required for connection
ALFA_BAAS_CERT_PATH=/path/to/transport.cer
ALFA_BAAS_KEY_PATH=/path/to/transport.key

# 2. Business Logic Signing (CMS/PKCS#7) - Required for creating payments/registries
ALFA_BAAS_SIGNING_CERT_PATH=/path/to/signing.cer
ALFA_BAAS_SIGNING_KEY_PATH=/path/to/signing.key

# 3. Credentials
ALFA_BAAS_CLIENT_ID=your-client-id
ALFA_BAAS_CLIENT_SECRET=your-client-secret
ALFA_BAAS_ENV=sandbox

---

3. Core Concepts

3.1 Facades (Laravel)

Use the facades for clean, static access.

• AlfaBank: Access BaaS endpoints (Payments, Accounts, Salary).
• Sbp: Access SBP endpoints (QR Codes, C2B/B2C).

3.2 DTOs (Data Transfer Objects)

Never pass raw arrays. Use DTOs to ensure your data is valid before it leaves your server.

Example:

use Apoloz\AlfaBank\Data\Payments\PaymentData;

$payment = new PaymentData(
    amount: 100.00,
    payerName: 'My Company',
    // ... mandatory fields are enforced here
);

3.3 Pagination

Iterate through large lists effortlessly.

use Apoloz\AlfaBank\Requests\Statement\GetTransactionsRequest;

$paginator = AlfaBank::paginate(new GetTransactionsRequest($accountNumber));

foreach ($paginator as $transaction) {
    // $transaction is a strictly typed DTO
    echo $transaction->amount;
}

---

4. Advanced Security

4.1 SBP Body Signing

The SDK handles the complex JSON Canonicalization (JCS) and RSA-SHA256 signing required by the SBP protocol automatically in the SbpConnector.

4.2 Webhook Verification

To handle webhooks securely:

1. Define a route using the macro:

   Route::alfaWebhooks('/api/webhooks/alfa');
   

2. Listen for the AlfaWebhookReceived event.
3. The SDK middleware verifies the authenticity of the request.

---

5. Troubleshooting

"Interface not found"

Ensure you have run composer update to install saloonphp/pagination-plugin.

"Certificate not found"

Check your .env paths. The files must be readable by the PHP process (usually www-data).

"Invalid Signature"

Ensure you are using the correct Signing Key (not the Transport key) for business logic operations like CmsSigner::sign().

---

6. Architecture & Data Flow

This section visualizes how data moves through the SDK, explaining the invisible work performed by the library (Security, Serialization, Transport).

6.1 General Request Lifecycle (BaaS)

When you send a request (e.g., creating a payment), the SDK automatically handles DTO serialization, mTLS authentication, and response mapping.

sequenceDiagram
    participant User as Client App
    participant SDK as SDK Facade
    participant DTO as Request DTO
    participant Con as Connector
    participant API as Alfa Bank API

    User->>DTO: Instantiate (Strict Typing)
    User->>SDK: send(Request)
    SDK->>Con: Serialize DTO to JSON
    Con->>Con: Attach mTLS Certificates
    Con->>Con: Attach OAuth Token
    Con->>API: HTTPS Request (Signed/Encrypted)
    API-->>Con: Raw JSON Response
    Con->>SDK: Map JSON to Response DTO
    SDK-->>User: Return Response Object

6.2 SBP Body Signing (JCS)

The Faster Payments System (SBP) requires a specific "Body Signing" mechanism. The SDK implements JSON Canonicalization Scheme (JCS) to ensure the signature is valid regardless of key order.

flowchart TD
    A[Raw Request Body (Array)] -->|CmsSigner::canonicalize| B(Recursive Key Sort & JSON Encode)
    B -->|OpenSSL RSA-SHA256| C{Sign with Private Key}
    C -->|Base64 Encode| D[Signature String]
    D -->|Add Header| E[Authorization: Base64]
    E -->|mTLS Connection| F((Alfa Bank SBP Gateway))
    style B fill:#f9f,stroke:#333,stroke-width:2px
    style C fill:#bbf,stroke:#333,stroke-width:2px

6.3 Webhook Processing

The SDK acts as a secure gatekeeper for incoming webhooks, verifying their origin before dispatching them to your application logic.

sequenceDiagram
    participant Bank as Alfa Bank
    participant Route as Laravel Route
    participant Mid as Middleware
    participant Factory as WebhookFactory
    participant Event as AlfaWebhookReceived

    Bank->>Route: POST /webhooks/alfa
    Route->>Mid: Intercept Request
    Mid->>Mid: Verify Credentials / Signature
    alt Invalid
        Mid-->>Bank: 401 Unauthorized
    else Valid
        Mid->>Factory: Extract Payload
        Factory->>Factory: Detect Type (BaaS vs SBP)
        Factory->>Event: Dispatch Typed DTO
        Event-->>Route: Processing Complete
        Route-->>Bank: 200 OK
    end

---

Generated by Alfa Bank SDK Team