PHPackages baraja-core/fio-payment-authorizator - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Payment Processing](/categories/payments) 4. / 5. baraja-core/fio-payment-authorizator ActiveLibrary[Payment Processing](/categories/payments) baraja-core/fio-payment-authorizator ==================================== FIO payment authorizator. v2.1.2(1y ago)32.7k1PHPPHP ^8.1CI passing Since Aug 29Pushed 4mo ago1 watchersCompare [ Source](https://github.com/baraja-core/fio-payment-authorizator)[ Packagist](https://packagist.org/packages/baraja-core/fio-payment-authorizator)[ Docs](https://github.com/baraja-core/fio-payment-authorizator)[ RSS](/packages/baraja-core-fio-payment-authorizator/feed)WikiDiscussions master Synced 2d ago READMEChangelog (10)Dependencies (9)Versions (22)Used By (1) ![BRJ logo](https://camo.githubusercontent.com/813c67e02a7ab7e4dc900316a4521c3ddf5846fe2cabba7140f3f4b78afda198/68747470733a2f2f63646e2e62726a2e6170702f696d616765732f62726a2d6c6f676f2f6c6f676f2d6461726b2e706e67) [BRJ organisation](https://brj.app) --- Fio Bank Payment Authorizator ============================= [](#fio-bank-payment-authorizator) [![Integrity check](https://github.com/baraja-core/fio-payment-authorizator/workflows/Integrity%20check/badge.svg)](https://github.com/baraja-core/fio-payment-authorizator/workflows/Integrity%20check/badge.svg) 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. ✨ Key Features -------------- [](#sparkles-key-features) - **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 🏗️ Architecture --------------- [](#building_construction-architecture) 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 │ │ │ └─────────────────────────┘ │ └───────────────────────────────┘ ``` 🧩 Components ------------ [](#jigsaw-components) ### FioPaymentAuthorizator [](#fiopaymentauthorizator) 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) ### TransactionResult [](#transactionresult) A value object representing the complete API response, containing: PropertyTypeDescription`accountId``int`Bank account number`bankId``int`Bank identifier (routing number)`currency``string`Account currency (e.g., CZK, EUR)`iban``string`International Bank Account Number`bic``string`Bank Identifier Code (SWIFT)`openingBalance``float`Balance at the start of the period`closingBalance``float`Balance at the end of the period`dateStart``DateTimeInterface`Start of the transaction period`dateEnd``DateTimeInterface`End of the transaction period`idFrom``int`First transaction ID in the response`idTo``int`Last transaction ID in the response`transactions``Transaction[]`Array of transaction objects### Transaction [](#transaction) Represents a single bank transaction with comprehensive details: PropertyTypeDescription`id``int`Unique transaction identifier`date``DateTimeInterface`Transaction date`price``float`Transaction amount (positive for incoming, negative for outgoing)`currency``string`Transaction currency`toAccount``?string`Counterparty account number`toAccountName``?string`Counterparty account name`toBankCode``?int`Counterparty bank code`toBankName``?string`Counterparty bank name`constantSymbol``?int`Constant symbol (KS)`variableSymbol``?int`Variable symbol (VS)`specificSymbol``?int`Specific symbol (SS)`userNotice``?string`User notice/reference`toMessage``?string`Message for recipient`type``?string`Transaction type`sender``?string`Sender identification`message``?string`General message`comment``?string`Additional comment`bic``?string`Counterparty BIC/SWIFT code`idTransaction``?int`Alternative transaction ID**Key Methods:** - `isVariableSymbol(int $vs): bool` - Checks if transaction matches a variable symbol - `isContainVariableSymbolInMessage(int|string $vs): bool` - Searches for VS in message fields ### FioPaymentException [](#fiopaymentexception) Custom exception class for handling Fio-specific errors: - Empty API responses - Invalid API keys - Service unavailability - Malformed data 📦 Installation -------------- [](#package-installation) It's best to use [Composer](https://getcomposer.org) for installation, and you can also find the package on [Packagist](https://packagist.org/packages/baraja-core/fio-payment-authorizator) and [GitHub](https://github.com/baraja-core/fio-payment-authorizator). 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. ### Requirements [](#requirements) - PHP 8.1 or higher - `baraja-core/bank-transaction-authorizator` ^2.0 (installed automatically) - Optional: `nette/caching` for persistent caching support 🔑 Obtaining API Key ------------------- [](#key-obtaining-api-key) 1. Log in to your [Fio Bank Internet Banking](https://ib.fio.cz/) 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. 🚀 Basic Usage ------------- [](#rocket-basic-usage) ### Standalone Usage [](#standalone-usage) ``` 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' ); } ``` ### Order Authorization [](#order-authorization) 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(), ]); } ); ``` ### Using with Nette Framework [](#using-with-nette-framework) 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... } } ``` ### Enabling Caching [](#enabling-caching) 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. 🔍 Advanced Usage ---------------- [](#mag-advanced-usage) ### Checking Variable Symbol in Messages [](#checking-variable-symbol-in-messages) 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'; } ``` ### Filtering Transactions [](#filtering-transactions) ``` $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 ); ``` ### Error Handling [](#error-handling) ``` 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'); } } ``` ⚠️ API Rate Limits ------------------ [](#warning-api-rate-limits) 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 📚 Related Packages ------------------ [](#books-related-packages) - [`baraja-core/bank-transaction-authorizator`](https://github.com/baraja-core/bank-transaction-authorizator) - Base package providing the `BaseAuthorizator` interface - Works with other bank authorizators following the same interface 👥 Author -------- [](#busts_in_silhouette-author) **Jan Barasek** - 📄 License --------- [](#page_facing_up-license) `baraja-core/fio-payment-authorizator` is licensed under the MIT license. See the [LICENSE](https://github.com/baraja-core/fio-payment-authorizator/blob/master/LICENSE) file for more details. ### Health Score 44 — FairBetter than 92% of packages Maintenance57 Moderate activity, may be stable Popularity19 Limited adoption so far Community11 Small or concentrated contributor base Maturity76 Established project with proven stability Bus Factor1 Top contributor holds 98.1% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~102 days Recently: every ~303 days Total 18 Last Release 703d ago Major Versions v1.4.0 → v2.0.02021-02-09 PHP version history (5 changes)v1.0.0PHP >=7.1.0 v1.2.1PHP >=7.4.0 v1.4.0PHP ^7.4 || ^8.0 v2.0.0PHP ^8.0 v2.1.0PHP ^8.1 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/3382204?v=4)[baraja](/maintainers/baraja)[@baraja](https://github.com/baraja) --- Top Contributors [![janbarasek](https://avatars.githubusercontent.com/u/4738758?v=4)](https://github.com/janbarasek "janbarasek (53 commits)")[![dependabot-preview[bot]](https://avatars.githubusercontent.com/in/2141?v=4)](https://github.com/dependabot-preview[bot] "dependabot-preview[bot] (1 commits)") --- Tags authorizatorbankfiofio-payment-authorizatorpayment ### Code Quality Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/baraja-core-fio-payment-authorizator/health.svg) ``` [![Health](https://phpackages.com/badges/baraja-core-fio-payment-authorizator/health.svg)](https://phpackages.com/packages/baraja-core-fio-payment-authorizator) ``` ### Alternatives [omnipay/paypal PayPal gateway for Omnipay payment processing library 3156.8M53](/packages/omnipay-paypal)[eduardokum/laravel-boleto Biblioteca com boletos para o laravel 626351.9k2](/packages/eduardokum-laravel-boleto)[tbbc/money-bundle This is a Symfony bundle that integrates moneyphp/money library (Fowler pattern): https://github.com/moneyphp/money. 1961.9M](/packages/tbbc-money-bundle)[2checkout/2checkout-php 2Checkout PHP Library 83740.3k2](/packages/2checkout-2checkout-php)[smhg/sepa-qr-data Generate QR code data for SEPA payments 61717.2k5](/packages/smhg-sepa-qr-data)[omnipay/dummy Dummy driver for the Omnipay payment processing library 271.2M33](/packages/omnipay-dummy) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)