sashalenz / privat24-business-api

1.2.0 2026-08-25 14:26 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^10.0||^11.0||^12.0||^13.0
• spatie/laravel-data: ^4.11
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^2.9
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.1.1||^7.10.0
• orchestra/testbench: ^9.0.0||^8.22.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-arch: ^3.0
• pestphp/pest-plugin-laravel: ^3.0
• phpstan/extension-installer: ^1.3
• phpstan/phpstan-deprecation-rules: ^1.1
• phpstan/phpstan-phpunit: ^1.3
• spatie/laravel-ray: ^1.35

MIT

• sashalenz

• laravel
• sashalenz
• privat24-business-api

Published on Packagist.org on 2026-08-25 16:43 UTC

README

This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.

Installation

You can install the package via composer:

composer require sashalenz/privat24-business-api

You can publish the config file with:

php artisan vendor:publish --tag="privat24-business-api-config"

This is the contents of the published config file:

return [
];

Usage

Виписки (statements)

use Sashalenz\Privat24BusinessApi\Privat24BusinessApi;

// Транзакції за період (з курсорною пагінацією)
$response = Privat24BusinessApi::statements()
    ->token($token)
    ->transactions($startDate, $endDate, $acc, $followId, 20);

foreach ($response->transactions as $tx) {
    // Sashalenz\Privat24BusinessApi\Types\Transaction
}

// Поточний операційний день / фінальна виписка за попередній день
Privat24BusinessApi::statements()->token($token)->interimTransactions();
Privat24BusinessApi::statements()->token($token)->finalTransactions();

// Баланси
Privat24BusinessApi::statements()->token($token)->balance($startDate);
Privat24BusinessApi::statements()->token($token)->interimBalance();
Privat24BusinessApi::statements()->token($token)->finalBalance();

// Health-check: phase === 'WRK' — банк приймає запити
Privat24BusinessApi::statements()->token($token)->settings();

Платежі (proxy/payment)

Створений через API платіж не рухає кошти: він зʼявляється у «Приват24 для бізнесу» зі статусом new і чекає підпису КЕП у кабінеті. До підписання його можна видалити через delete().

use Sashalenz\Privat24BusinessApi\Privat24BusinessApi;
use Sashalenz\Privat24BusinessApi\RequestData\Payments\CreatePaymentRequest;

// Створення платіжного доручення
$response = Privat24BusinessApi::payments()
    ->token($token)
    ->create(new CreatePaymentRequest(
        document_number: '42',
        payer_account: 'UA77305299...',          // IBAN відправника
        payment_naming: 'ТОВ "Отримувач"',
        payment_amount: '1250.50',               // decimal-рядок
        payment_destination: 'Оплата за послуги згідно рахунку №42',
        recipient_account: 'UA74305299...',      // IBAN отримувача
        recipient_nceo: '12345678',              // ЄДРПОУ/ІПН ('0000000000' — фізособа)
    ));

$response->payment_ref;       // референс — він же REF у виписці після проведення
$response->payment_pack_ref;

// Стан платежу
$state = Privat24BusinessApi::payments()->token($token)->get($response->payment_ref);
$state->payment_status;       // 'new' — очікує підписання

// Видалення непідписаного платежу (POST, 204)
Privat24BusinessApi::payments()->token($token)->delete($response->payment_ref);

Зарплатний проєкт і реєстри (pay/mp, pay/maspay)

Реєстр — це один документ, який платить багатьом. У виписці він приходить одним дебетом, а не N.

🔴 Головне, що відрізняє реєстр від поштучного платежу: рядок адресується ідентифікатором людини в довіднику банку, а не IBAN-ом. Людину з ідеальними реквізитами на вашому боці неможливо оплатити реєстром, доки її не заведено в проєкт.

use Sashalenz\Privat24BusinessApi\Privat24BusinessApi;
use Sashalenz\Privat24BusinessApi\Enums\SalaryGroupType;
use Sashalenz\Privat24BusinessApi\RequestData\Salary\{AddRecordRequest, CreatePacketRequest, UpdateReceiverRequest};

$api = Privat24BusinessApi::salaryProject()->token($token);

// Проєкти клієнта — разом із комісією банку (rko) за кожним
$api->groups();

// Знайти людину в довіднику (filter шукає по ПІБ / ІПН / табельному)
$found = $api->receivers(SalaryGroupType::SALARY, filter: '1234567890');

// Або завести. `id` з відповіді — це те, чим адресується рядок реєстру:
// збережіть його у себе, іншого способу знайти людину потім немає.
$receiverId = $api->updateReceiver(new UpdateReceiverRequest(
    pan: 'UA743052990000026002000000002',
    group: SalaryGroupType::SALARY,
    fio: ['Мельник', 'Тарас'],
    inn: '9876543210',
    tabn: '7',
))->id;

$registers = Privat24BusinessApi::salaryRegisters()->token($token);

$packet = $registers->create(new CreatePacketRequest(
    group: SalaryGroupType::SALARY,
    salary: true,                       // це саме зарплата, а не інша масова виплата
    packetName: 'Тиждень 34',
));

$registers->addRecord($packet->reference, new AddRecordRequest(
    receiver: $receiverId,
    amount: 1250.50,
    comment: 'Зарплата за тиждень 34',
));

$registers->validatePacket($packet->reference);   // віддати банку на перевірку

$registers->records($packet->reference);          // статус кожного рядка + errorCode
$registers->header($packet->reference)->status;   // PacketStatus

Підпис. Як і поштучний платіж, реєстр нічого не рухає, доки його не підписали. На відміну від поштучного платежу, ендпоїнта підпису для реєстру немає — підписується він у «Приват24 для бізнесу», двома підписами (SB бухгалтер → SD директор → S$ обидва).

Редагування. Рядки додаються й прибираються лише поки пакет у PacketStatus::CREATED (isEditable()). Після перевірки рядок, який банк не прийняв, лишається у N$ з errorCode — його можна виправити, не втрачаючи весь пакет.

⚠️ Невідоме, і воно вирішує звірку. Чи reference пакета доїжджає у виписку як DLR дебету — так, як це робить payment_pack_ref поштучного платежу, — документація не каже. Доки один реальний реєстр цього не покаже, не будуйте звірку на припущенні, що доїжджає.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• sashalenz
• All Contributors

License

The MIT License (MIT). Please see License File for more information.