voharaa / privatbank-autoclient
Unofficial PHP client for the PrivatBank Autoclient API (Privat24 for Business): account balances and statements.
Requires
- php: ^8.3
- php-http/discovery: ^1.20
- psr/http-client: ^1.0
- psr/http-client-implementation: ^1.0
- psr/http-factory: ^1.1
- psr/http-factory-implementation: ^1.0
Requires (Dev)
- guzzlehttp/guzzle: ^8.5
- laravel/pint: ^1.32
- pestphp/pest: ^4.7
- phpstan/phpstan: ^2.3
- symfony/var-dumper: ^7.4
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
English · Українська
Unofficial. This package is not made, endorsed or supported by PrivatBank.
PHP client for the PrivatBank Autoclient API (Privat24 for Business): account balances and transactions. Built against the bank's API documentation version 3.0.0.
- Works with any PSR-18 HTTP client (Guzzle, Symfony HttpClient, …)
- Typed
BalanceandTransactionobjects with readable property names - Pagination handled for you, lazily
Requirements
- PHP 8.3 or newer
- An Autoclient API token: Privat24 for Business → «Інтеграція (Автоклієнт)» → «Підключити API». For legal entities the API is available on the «Бізнес Комфорт» and «Бізнес ПРО» plans, for sole proprietors (ФОП) on any plan.
Installation
Install the package via Composer:
composer require voharaa/privatbank-autoclient
The package needs a PSR-18 HTTP client. Ensure that the php-http/discovery Composer plugin is allowed to run
(it installs one for you), or install a client manually if your project does not already have one:
composer require guzzlehttp/guzzle
Any other PSR-18 client with PSR-17 factories (for example Symfony HttpClient) works too.
Laravel
Laravel already ships with Guzzle, so the package works right after composer require voharaa/privatbank-autoclient.
There is no service provider or facade yet; register the client yourself:
// config/services.php 'privatbank' => [ 'token' => env('PRIVATBANK_TOKEN'), ], // app/Providers/AppServiceProvider.php use Voharaa\PrivatbankAutoclient\Client; public function register(): void { $this->app->singleton(Client::class, fn () => Client::make(config('services.privatbank.token'))); }
Then inject Client wherever you need it. Laravel's Http facade is not a PSR-18 client, so the package
uses Guzzle directly and Http::fake() does not affect it.
Quick start
use Voharaa\PrivatbankAutoclient\Client; $client = Client::make(getenv('PRIVATBANK_TOKEN')); $transactions = $client->statements()->transactions(new DateTimeImmutable('-7 days')); foreach ($transactions as $tx) { echo $tx->valueDate, ' ', $tx->isCredit() ? '+' : '-', $tx->amount, ' ', $tx->currency, ' ', $tx->purpose, PHP_EOL; }
⚠️ Every
foreachover a cursor sends the requests again. Results are fetched page by page while you iterate, nothing is cached. If you need the data more than once, call->all()once and work with the array. The bank recommends at most one request per second.
Usage
Settings
$settings = $client->statements()->settings(); $settings->isApiAvailable(); // false during the bank's maintenance windows $settings->today; // "30.03.2020 00:00:00"
Balances
$balances = $client->statements()->balances( startDate: new DateTimeImmutable('2026-11-01'), endDate: new DateTimeImmutable('2026-11-15'), // optional account: 'UA943052990000026100050001037', // optional, all active accounts if omitted ); foreach ($balances as $balance) { echo $balance->date, ' ', $balance->account, ': ', $balance->closingBalance, ' ', $balance->currency, PHP_EOL; }
For a date range the API returns one row per account per day, so 10 accounts over 30 days are about 300 rows.
$balance->date tells which day a row is for. For today's balances only, pass today as startDate:
$today = $client->statements()->balances(new DateTimeImmutable('today'))->all(); // one row per account
Transactions
$transactions = $client->statements()->transactions(new DateTimeImmutable('2026-11-01'))->all(); foreach ($transactions as $tx) { $tx->id; // unique per row, use it to deduplicate $tx->instructionKey(); // REF + REFN: the payment instruction, see below $tx->direction; // TransactionDirection::Debit or ::Credit $tx->status; // TransactionStatus::Posted, ::Processing, ::Reversed, ::Rejected $tx->counterpartyName; $tx->counterpartyEdrpou; }
own* properties describe your account (AUT_MY_* in the API), counterparty* the other side (AUT_CNTR_*).
A transfer between two of your own accounts appears twice: as a debit on one account and a credit on the other.
Both rows have the same instructionKey() but different ids.
Raw API data
Every response object (Transaction, Balance, Settings, ExchangeRates, …) keeps the row exactly as the API returned it in $raw,
including fields that have no property of their own. Nothing is converted: empty strings stay "",
while the matching property is null.
$tx->raw; // ['ID' => '557091731', 'REF' => 'DNCHK0108B1WKX', 'SUM_E' => '0.01', ...] $tx->raw['TRANTYPE']; // "C" json_encode($tx->raw); // e.g. to store the original row in a database
All of them implement HasRawResponse, so you can handle any response object the same way:
use Voharaa\PrivatbankAutoclient\Contracts\HasRawResponse; function storeRaw(HasRawResponse $response): void { DB::table('bank_rows')->insert(['payload' => json_encode($response->raw())]); }
Interim and final statements
$client->statements()->interimBalances(); // from the last operating day to today $client->statements()->finalBalances(); // the last closed day $client->statements()->interimTransactions(); $client->statements()->finalTransactions();
Currency rates
$rates = $client->currency()->rates(); $usd = $rates->get('USD'); // null if the API did not return this currency $usd->buy->rate; // "26.0700000", the bank buys USD at this rate $usd->sell->rate; // "26.3200000", the bank sells USD at this rate $usd->buy->delta; // "-0.0600000", change of the rate $usd->buy->nbuRate; // "26.1888140", official NBU rate $usd->buy->date; // "18-05-2018 14:00:01" $usd->rate(CurrencyRateType::Sell); // same as $usd->sell $rates->currencies(); // ['USD', 'EUR', ...] $rates->fromCache; // true if the API served cached data $rates->cacheTime; // Unix time in milliseconds, null if not cached // History for a period of at most 15 days (checked before sending the request) $history = $client->currency()->history(new DateTimeImmutable('-7 days'), new DateTimeImmutable('today')); foreach ($history->forCurrency('USD') as $day) { echo $day->date, ': ', $day->buy, ' / ', $day->sell, ' (NBU ', $day->nbuRate, ')', PHP_EOL; } $history->rates; // list<HistoricalRate>: one row per currency per day, oldest first $history->dates(); // ['11-11-2026', '12-11-2026', ...], days without rates (weekends) are skipped $history->forDate(new DateTimeImmutable('2026-11-17')); // all currencies for one day $history->currencies(); // ['CHF', 'EUR', 'USD', 'PLZ', ...]
The history has a different shape than the current rates: each HistoricalRate holds both sides
(buy, sell, buyDelta, sellDelta, nbuRate) for one day, and rate() / delta() take a CurrencyRateType.
Currency codes are kept as the API returns them, which is not always ISO 4217 (the bank sends PLZ for the zloty).
Note: the real
proxy/currency/historyresponse differs from the bank's documentation, which shows the same shape asproxy/currency. The API actually returnsdata.history: a list of rows withdate,currencyCode,nbuRate,rate_b,rate_b_delta,rate_sandrate_s_delta. The library maps this real format (checked on 17.11.2026).
ExchangeRates, ExchangeRatesHistory and the objects inside them implement HasRawResponse.
Notes on the data
- Amounts are strings (
"250.75") to keep their precision. Usebcmathor a money library for arithmetic. - Dates are strings exactly as the API returns them, in local Kyiv time:
"d.m.Y H:i:s"or"d.m.Y". Balance::$closedAtisnullfor accounts that are not closed.Balance::$isFinalisfalsefor days that are not yet in the final statement (the last operating day and today).- Some fields described in the bank's docs are not always returned (e.g.
Transaction::$technicalIdis usuallynull).
Error handling
use Voharaa\PrivatbankAutoclient\Exceptions\ApiException; use Voharaa\PrivatbankAutoclient\Exceptions\TransportException; try { $balances = $client->statements()->balances(new DateTimeImmutable('-1 day'))->all(); } catch (ApiException $e) { // The API answered with an error: wrong token (401), disabled account (403), status !== "SUCCESS", 5xx… $e->statusCode; // HTTP status, also $e->getCode() $e->errorCode; // API error code, e.g. "VE005" $e->serviceCode; // e.g. "PMTSRV0112" $e->requestId; // quote it when contacting the bank's support } catch (TransportException $e) { // No usable answer: network error, invalid JSON, unexpected response format }
Because cursors are lazy, these exceptions are thrown while iterating (or in ->all()), not when calling balances().
Supported endpoints
| Endpoint | Method |
|---|---|
statements/settings |
settings() |
statements/balance |
balances() |
statements/balance/interim |
interimBalances() |
statements/balance/final |
finalBalances() |
statements/transactions |
transactions() |
statements/transactions/interim |
interimTransactions() |
statements/transactions/final |
finalTransactions() |
proxy/currency |
currency()->rates() |
proxy/currency/history |
currency()->history() |
Not supported yet
- Group mode (
?id=for groups of sole proprietors) - Payments: creating, signing, deleting, SWIFT and other currency payments
- Electronic document management (EDO, invoices, tax invoices)
- Electronic reporting
- Salary project and payslips
- Corporate cards
- Counterparty checks, payment receipts, acquiring statements
Security
Never commit your token. It gives read access to your accounts (and, if not restricted in the app settings, the ability to create payments). In Privat24 for Business you can limit the token to «Отримання балансів і транзакцій за рахунками» under «Обмеження по сервісам».
Development
composer test # Pest, no network access needed composer analyse # PHPStan, level max composer lint # Pint
License
MIT, see LICENSE.