BRJ organisation

A PHP library for seamless integration with Fio Bank's API, enabling automatic retrieval of bank transactions and authorization of orders based on variable symbols. Perfect for e-commerce platforms, billing systems, and any application requiring automated payment verification.

• Automatic Transaction Retrieval - Fetches transactions from the last month via Fio Bank's REST API
• Variable Symbol Matching - Authorizes orders by matching variable symbols in transactions
• Smart Symbol Detection - Searches for variable symbols in message fields when not found in the dedicated field
• Built-in Caching - Optional Nette Cache integration to reduce API calls (15-minute cache expiration)
• CSV Parsing - Efficiently parses Fio Bank's CSV response format
• Extensible Architecture - Implements BaseAuthorizator interface for consistent behavior across different bank integrations
• Type-Safe - Fully typed PHP 8.1+ codebase with strict types

The library follows a clean, layered architecture with clear separation of concerns:

┌─────────────────────────────────────────────────────────────────────┐
│                        Your Application                             │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    FioPaymentAuthorizator                           │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  • Manages API communication                                 │   │
│  │  • Handles caching layer                                     │   │
│  │  • Provides authOrders() method for bulk authorization       │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                    ┌──────────────┴──────────────┐
                    ▼                              ▼
┌───────────────────────────────┐  ┌───────────────────────────────┐
│      TransactionResult        │  │      FioPaymentException      │
│  ┌─────────────────────────┐ │  │  ┌─────────────────────────┐  │
│  │ • Account metadata      │ │  │  │ • API errors            │  │
│  │ • IBAN, BIC             │ │  │  │ • Empty responses       │  │
│  │ • Balance information   │ │  │  │ • Service unavailable   │  │
│  │ • Date range            │ │  │  └─────────────────────────┘  │
│  │ • Transaction list      │ │  └───────────────────────────────┘
│  └─────────────────────────┘ │
└───────────────────────────────┘
                │
                ▼
┌───────────────────────────────┐
│         Transaction           │
│  ┌─────────────────────────┐ │
│  │ • Transaction ID        │ │
│  │ • Date, Price, Currency │ │
│  │ • Variable/Constant/    │ │
│  │   Specific symbols      │ │
│  │ • Account details       │ │
│  │ • Messages & comments   │ │
│  └─────────────────────────┘ │
└───────────────────────────────┘

The main entry point of the library. Extends BaseAuthorizator from the baraja-core/bank-transaction-authorizator package.

Responsibilities:

• Constructs API URLs with the provided private key
• Downloads transaction data from Fio Bank's REST API
• Manages static and persistent caching
• Normalizes and validates API responses
• Provides the authOrders() method for bulk authorization (inherited from BaseAuthorizator)

A value object representing the complete API response, containing:

Represents a single bank transaction with comprehensive details:

Key Methods:

• isVariableSymbol(int $vs): bool - Checks if transaction matches a variable symbol
• isContainVariableSymbolInMessage(int|string $vs): bool - Searches for VS in message fields

Custom exception class for handling Fio-specific errors:

• Empty API responses
• Invalid API keys
• Service unavailability
• Malformed data

It's best to use Composer for installation, and you can also find the package on Packagist and GitHub.

To install, simply use the command:

$ composer require baraja-core/fio-payment-authorizator

You can use the package manually by creating an instance of the internal classes, or register a DIC extension to link the services directly to the Nette Framework.

• PHP 8.1 or higher
• baraja-core/bank-transaction-authorizator ^2.0 (installed automatically)
• Optional: nette/caching for persistent caching support

1. Log in to your Fio Bank Internet Banking
2. Navigate to Settings > API
3. Generate a new API token with read permissions
4. Copy the token - this is your privateKey

Security Note: Never commit your API key to version control. Use environment variables or a secure configuration management system.

use Baraja\FioPaymentAuthorizator\FioPaymentAuthorizator;
use Baraja\FioPaymentAuthorizator\Transaction;

// Create instance with your API key
$fio = new FioPaymentAuthorizator('your-private-api-key');

// Get all transactions from the last month
$result = $fio->process();

// Access account information
echo 'Account: ' . $result->getIban() . PHP_EOL;
echo 'Currency: ' . $result->getCurrency() . PHP_EOL;
echo 'Opening Balance: ' . $result->getOpeningBalance() . PHP_EOL;
echo 'Closing Balance: ' . $result->getClosingBalance() . PHP_EOL;

// Iterate through transactions
foreach ($result->getTransactions() as $transaction) {
    echo sprintf(
        "[%s] %s %s - VS: %s\n",
        $transaction->getDate()->format('Y-m-d'),
        $transaction->getPrice(),
        $transaction->getCurrency(),
        $transaction->getVariableSymbol() ?? 'N/A'
    );
}

The library can automatically authorize orders based on variable symbols:

// Array of variable symbols from unpaid orders
$unauthorizedVariables = [123456, 789012, 345678];

// Authorize orders - the callback is called for each matched transaction
$fio->authOrders(
    $unauthorizedVariables,
    function (Transaction $transaction): void {
        // Mark order as paid in your system
        $orderId = $transaction->getVariableSymbol();

        // Example: Update order status in database
        $this->orderRepository->markAsPaid($orderId, [
            'transactionId' => $transaction->getId(),
            'amount' => $transaction->getPrice(),
            'paidAt' => $transaction->getDate(),
        ]);
    }
);

Register the service in your config.neon:

parameters:
    fio:
        privateKey: %env.FIO_API_KEY%

services:
    - Baraja\FioPaymentAuthorizator\FioPaymentAuthorizator(%fio.privateKey%)

Then inject it in your presenter or service:

final class PaymentPresenter extends Nette\Application\UI\Presenter
{
    public function __construct(
        private FioPaymentAuthorizator $fio,
    ) {
    }

    public function actionAuthorize(): void
    {
        $result = $this->fio->process();
        // Process transactions...
    }
}

To reduce API calls and improve performance, enable caching by providing a Nette Cache storage:

services:
    - Baraja\FioPaymentAuthorizator\FioPaymentAuthorizator(
        privateKey: %fio.privateKey%
        storage: @cacheStorage
    )

Or manually:

use Nette\Caching\Storages\FileStorage;

$storage = new FileStorage('/path/to/cache');
$fio = new FioPaymentAuthorizator('your-private-api-key', $storage);

The cache expires after 15 minutes and is tagged with fio, bank, and payment for easy invalidation.

Some payment systems (especially international transfers) may include the variable symbol in the message field instead of the dedicated VS field. The library handles this automatically:

$transaction = $result->getTransactions()[0];

// This checks both the VS field AND message fields
if ($transaction->isVariableSymbol(123456)) {
    echo 'Variable symbol found!';
}

// Check only in message fields
if ($transaction->isContainVariableSymbolInMessage(123456)) {
    echo 'Found in message content';
}

$transactions = $fio->getTransactions();

// Filter incoming payments only
$incoming = array_filter(
    $transactions,
    fn(Transaction $t) => $t->getPrice() > 0
);

// Filter by date range
$startDate = new DateTime('2024-01-01');
$filtered = array_filter(
    $transactions,
    fn(Transaction $t) => $t->getDate() >= $startDate
);

// Filter by specific bank
$fioBankCode = 2010;
$fioTransfers = array_filter(
    $transactions,
    fn(Transaction $t) => $t->getToBankCode() === $fioBankCode
);

use Baraja\FioPaymentAuthorizator\FioPaymentException;

try {
    $result = $fio->process();
} catch (FioPaymentException $e) {
    // Handle Fio-specific errors
    if (str_contains($e->getMessage(), 'API key')) {
        // Invalid API key
        $this->logger->error('Invalid Fio API key');
    } elseif (str_contains($e->getMessage(), 'down')) {
        // Service temporarily unavailable
        $this->logger->warning('Fio API temporarily unavailable');
    }
}

Fio Bank API has rate limiting in place:

• 30 seconds minimum interval between requests
• The built-in caching helps respect this limit
• Consider implementing a queue system for high-traffic applications

• baraja-core/bank-transaction-authorizator - Base package providing the BaseAuthorizator interface
• Works with other bank authorizators following the same interface

Jan Barasek - https://baraja.cz

baraja-core/fio-payment-authorizator is licensed under the MIT license. See the LICENSE file for more details.