PHPackages                             sashalenz/novapay-api - 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. [API Development](/categories/api)
4. /
5. sashalenz/novapay-api

ActiveLibrary[API Development](/categories/api)

sashalenz/novapay-api
=====================

NovaPay Business Cabinet API client for Laravel

1.0.2(1mo ago)0207↓27.8%MITPHPPHP ^8.2

Since May 26Pushed 1mo agoCompare

[ Source](https://github.com/sashalenz/novapay-api)[ Packagist](https://packagist.org/packages/sashalenz/novapay-api)[ Docs](https://github.com/sashalenz/novapay-api)[ RSS](/packages/sashalenz-novapay-api/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (3)Dependencies (26)Versions (4)Used By (0)

NovaPay API
===========

[](#novapay-api)

Laravel пакет для роботи з [NovaPay Business Cabinet API](https://business.novapay.ua/) v2.0.

Реалізовано всі 15 методів згідно офіційної документації «API інструкція (березень 2026)».

---

Встановлення
------------

[](#встановлення)

```
composer require sashalenz/novapay-api
```

Опублікуй конфіг:

```
php artisan vendor:publish --tag="novapay-api-config"
```

---

Конфігурація
------------

[](#конфігурація)

Додай у `.env`:

```
NOVAPAY_LOGIN=your_login
NOVAPAY_REFRESH_TOKEN=your_refresh_token
NOVAPAY_PUBLIC_CERTIFICATE="-----BEGIN RSA PUBLIC KEY-----\n...\n-----END RSA PUBLIC KEY-----"

# Необов'язково
NOVAPAY_API_URL=https://business.novapay.ua/Services/ClientAPIService.svc
NOVAPAY_TIMEOUT=30
```

`refresh_token` і `public_certificate` генеруються в особистому кабінеті: **Бізнес-кабінет → Система → Налаштування → API**.

---

Автентифікація
--------------

[](#автентифікація)

### JWT (рекомендований метод)

[](#jwt-рекомендований-метод)

Метод використовує одноразову ротацію токенів. Кожен виклик повертає **новий** `refresh_token` і `public_certificate`, які треба зберігати для наступного запиту.

```
use Sashalenz\NovapayApi\NovapayApi;
use Sashalenz\NovapayApi\NovapayCredentials;

// 1. З конфігу (.env)
$auth = NovapayApi::auth()->jwtFromConfig();

// 2. Явно (параметри)
$auth = NovapayApi::auth()->jwt(
    refreshToken: 'REFRESH_TOKEN',
    login: 'your_login',
    publicCertificate: '-----BEGIN RSA PUBLIC KEY-----...',
);

// 3. З DTO NovapayCredentials
$credentials = new NovapayCredentials(
    login: $bankAccount->novapay_login,
    refreshToken: $bankAccount->novapay_refresh_token,
    publicCertificate: $bankAccount->novapay_public_certificate,
);
$auth = NovapayApi::authenticateWith($credentials);

// 4. Напряму з моделі (через HasNovapayCredentials інтерфейс)
$auth = NovapayApi::authenticateAs($bankAccount);

$jwt             = $auth->jwt;               // токен для API запитів
$newRefreshToken = $auth->refresh_token;     // зберегти в БД
$newCertificate  = $auth->public_certificate; // зберегти в БД
```

> ⚠️ Після кожного успішного виклику старий `refresh_token` анульовується. Зберігай нові значення одразу після відповіді.

### Інтеграція з Eloquent моделлю

[](#інтеграція-з-eloquent-моделлю)

Реалізуй інтерфейс `HasNovapayCredentials` на моделі, де зберігаються облікові дані:

```
use Sashalenz\NovapayApi\HasNovapayCredentials;
use Sashalenz\NovapayApi\NovapayApi;

class BankAccount extends Model implements HasNovapayCredentials
{
    public function getNovapayLogin(): string
    {
        return $this->novapay_login;
    }

    public function getNovapayRefreshToken(): string
    {
        return $this->novapay_refresh_token;
    }

    public function getNovapayPublicCertificate(): string
    {
        return $this->novapay_public_certificate;
    }

    public function updateNovapayTokens(string $refreshToken, string $publicCertificate): void
    {
        $this->update([
            'novapay_refresh_token'      => $refreshToken,
            'novapay_public_certificate' => $publicCertificate,
        ]);
    }

    /**
     * Отримати JWT і одразу оновити токени в БД.
     */
    public function refreshNovapayJwt(): string
    {
        $response = NovapayApi::authenticateAs($this);

        $this->updateNovapayTokens(
            $response->refresh_token,
            $response->public_certificate,
        );

        return $response->jwt;
    }
}
```

Використання:

```
$jwt = $bankAccount->refreshNovapayJwt();

$accounts = NovapayApi::accounts()
    ->withJwt($jwt)
    ->list(clientId: $bankAccount->novapay_client_id);
```

> 💡 `NovapayCredentials::withUpdatedTokens()` дозволяє оновити токени immutably, зберігаючи той самий `login`:
>
> ```
> $updated = $credentials->withUpdatedTokens($auth->refresh_token, $auth->public_certificate);
> ```

### Легасі (буде відключено 31.08.2026)

[](#легасі-буде-відключено-31082026)

```
// Крок 1 — логін + пароль
$pre = NovapayApi::auth()->preAuthenticate(
    login: 'your_login',
    password: 'your_password',
);

// Крок 2 — підтвердження OTP
$session = NovapayApi::auth()->authenticate(
    tempPrincipal: $pre->temp_principal,
    codeOperationOtp: $pre->getCodeOperationOtp(),
    otpPassword: '123456',
);

$principal = $session->principal;

// Продовження сесії
$refreshed = NovapayApi::auth()->refresh($principal);
$newPrincipal = $refreshed->new_principal;
```

---

Методи API
----------

[](#методи-api)

Всі методи, окрім Auth, приймають токен через fluent-методи:

```
->withJwt(string $jwt)         // рекомендовано
->withPrincipal(string $p)     // легасі
```

### Клієнти (підприємства)

[](#клієнти-підприємства)

#### `GetClientsList` — список підприємств

[](#getclientslist--список-підприємств)

```
$response = NovapayApi::clients()
    ->withJwt($jwt)
    ->list();

foreach ($response->clients as $client) {
    echo $client->id;         // int
    echo $client->name;       // string
    echo $client->statecode;  // ЄДРПОУ / РНОКПП
}
```

---

### Рахунки

[](#рахунки)

#### `GetAccountsList` — список рахунків підприємства

[](#getaccountslist--список-рахунків-підприємства)

```
$response = NovapayApi::accounts()
    ->withJwt($jwt)
    ->list(clientId: 8);

foreach ($response->accounts as $account) {
    echo $account->id;          // int
    echo $account->IBAN;        // UA29358710...
    echo $account->currency;    // UAH
    echo $account->statuscode;  // AccountStatus enum
    echo $account->statuscode->label(); // 'Активний'
}
```

#### `GetAccountRest` — баланс рахунку

[](#getaccountrest--баланс-рахунку)

```
$response = NovapayApi::accounts()
    ->withJwt($jwt)
    ->balance(accountId: 49);

echo $response->confirmed_balance;  // float — підтверджений залишок
echo $response->available_balance;  // float — доступний залишок
echo $response->projected_balance;  // float — прогнозований залишок
```

#### `GetPaymentsList` — виписка платежів (XML)

[](#getpaymentslist--виписка-платежів-xml)

```
$response = NovapayApi::accounts()
    ->withJwt($jwt)
    ->payments(
        accountId: 49,
        dateFrom: '01.10.2024',   // dd.mm.yyyy
        dateTo: '31.10.2024',
        dateType: DateType::PaymentDate, // enum: 0-3
    );

// Рядок XML з CDATA
$rawXml = $response->payments;

// Або розпарсити у масив
$payments = $response->parsePayments();
foreach ($payments as $p) {
    echo $p['Amount'];
    echo $p['Purpose'];
    echo $p['StatusDocument']; // New, Processed, ...
}
```

#### `GetAccountExtract` — виписка з залишками (XML)

[](#getaccountextract--виписка-з-залишками-xml)

```
$response = NovapayApi::accounts()
    ->withJwt($jwt)
    ->extract(
        accountId: 49,
        dateFrom: '01.10.2024',
        dateTo: '31.10.2024',
    );

$data = $response->parseExtract();
// $data['head']     — масив заголовків (ExtractHead)
// $data['payments'] — масив транзакцій (Docs)
```

#### `GetAccountTurns` — обороти по рахунку

[](#getaccountturns--обороти-по-рахунку)

```
$response = NovapayApi::accounts()
    ->withJwt($jwt)
    ->turns(
        accountId: 49,
        dateFrom: '01.10.2024',
        dateTo: '31.10.2024',
    );

foreach ($response->turns as $turn) {
    echo $turn->date;         // '14.10.2024'
    echo $turn->IBAN;
    echo $turn->InRest;       // ?float — залишок на початок
    echo $turn->CrncyDebit;   // ?float — дебет
    echo $turn->CrncyCredit;  // ?float — кредит
    echo $turn->CrncyRest;    // ?float — залишок на кінець
}
```

---

### Платежі

[](#платежі)

#### `CreatePayment` — створення платежу

[](#createpayment--створення-платежу)

```
$response = NovapayApi::payments()
    ->withJwt($jwt)
    ->create([
        'account_id'      => 49,
        'OrgDate'         => '14.11.2024',       // dd.mm.yyyy
        'CreditCodeIBAN'  => 'UA29358700000067320000000001',
        'CreditName'      => 'ФОП Тест Тестовий',
        'CreditStateCode' => '1234567899',
        'Amount'          => '1250.00',
        'CurrencyTag'     => 'UAH',
        'Purpose'         => 'Оплата за товар згідно рахунку №42',
        // Необов'язково:
        'CreditCountry'      => 'UA',
        'CreditNotResident'  => false,
    ]);

if ($response->isSuccessful()) {
    // Платіж прийнято
}
```

#### `GetRecallPaymentsList` — платежі доступні для відкликання

[](#getrecallpaymentslist--платежі-доступні-для-відкликання)

```
$response = NovapayApi::payments()
    ->withJwt($jwt)
    ->recallableList();

foreach ($response->payments as $payment) {
    echo $payment->id;          // int
    echo $payment->orgdate;
    echo $payment->amount;      // ?float
    echo $payment->debitIBAN;
    echo $payment->creditIBAN;
    echo $payment->purpose;
}
```

#### `RecallPayment` — відкликання платежу

[](#recallpayment--відкликання-платежу)

```
$response = NovapayApi::payments()
    ->withJwt($jwt)
    ->recall(
        paymentId: 720,
        info: 'Відкликання через API',  // необов'язково
    );

echo $response->isSuccessful(); // bool
```

---

### Реєстри (Post-payment / КО)

[](#реєстри-post-payment--ко)

#### `GetRegister` — генерація виписки реєстру

[](#getregister--генерація-виписки-реєстру)

```
use Sashalenz\NovapayApi\Enums\RegisterFileExtension;

$response = NovapayApi::registers()
    ->withJwt($jwt)
    ->get(
        clientId: 8,
        from: '01.05.2025',
        into: '21.05.2025',
        fileExtension: RegisterFileExtension::XLS, // або CSV
    );

$statementId = $response->statement_id; // зберегти для download()
```

#### `DownloadRegister` — отримання посилання на файл

[](#downloadregister--отримання-посилання-на-файл)

```
$response = NovapayApi::registers()
    ->withJwt($jwt)
    ->download(id: $statementId);

echo $response->status;    // 'created' — файл готовий
echo $response->url;       // https://...novapay.ua/files/...xlsx
echo $response->file_name; // 'Реєстр переказів з 2025-05-01 до 2025-05-21.xlsx'
echo $response->file_type; // 'XLS'
```

> 💡 Файл може генеруватись асинхронно. Якщо `status !== 'created'` — викликай `download()` повторно через кілька секунд.

---

Proxy
-----

[](#proxy)

Всі ApiModel підтримують проксі:

```
NovapayApi::accounts()
    ->withJwt($jwt)
    ->proxy('http://proxy.example.com:8080')
    ->balance(49);
```

---

Обробка помилок
---------------

[](#обробка-помилок)

Всі методи кидають `NovapayApiException` при HTTP помилці або невалідній SOAP відповіді.

Логічні помилки (невірний токен, нема доступу) повертаються як успішна HTTP відповідь з `result = 'error'`:

```
use Sashalenz\NovapayApi\Exceptions\NovapayApiException;

try {
    $response = NovapayApi::accounts()
        ->withJwt($jwt)
        ->balance(accountId: 49);

    if (! $response->isSuccessful()) {
        // Логічна помилка API
        $error = $response->error;       // ?ApiError
        logger()->warning($error?->title, ['status' => $error?->status]);
        return;
    }

    // Успіх
    echo $response->confirmed_balance;

} catch (NovapayApiException $e) {
    // HTTP або SOAP помилка
    logger()->error('NovaPay API error', ['message' => $e->getMessage()]);
}
```

---

Enums
-----

[](#enums)

КласЗначення`AccountStatus``Active`, `Closed`, `OnApproval`, `Arrested``DateType``PaymentDate(0)`, `FromDate(1)`, `CreatedDate(2)`, `UpdatedDate(3)``RegisterFileExtension``XLS`, `CSV````
use Sashalenz\NovapayApi\Enums\AccountStatus;

AccountStatus::Active->label();      // 'Активний'
AccountStatus::Active->statusCode(); // 1
```

---

Тести
-----

[](#тести)

```
composer test
```

Всі тести використовують `Http::fake()` — реальні запити до NovaPay не виконуються.

---

Ліцензія
--------

[](#ліцензія)

MIT

###  Health Score

43

—

FairBetter than 89% of packages

Maintenance90

Actively maintained with recent releases

Popularity16

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~5 days

Total

3

Last Release

49d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/13202688?v=4)[Oleksandr Petrovskyi](/maintainers/sashalenz)[@sashalenz](https://github.com/sashalenz)

---

Top Contributors

[![sashalenz](https://avatars.githubusercontent.com/u/13202688?v=4)](https://github.com/sashalenz "sashalenz (4 commits)")

---

Tags

laravelsashalenznovapay-api

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/sashalenz-novapay-api/health.svg)

```
[![Health](https://phpackages.com/badges/sashalenz-novapay-api/health.svg)](https://phpackages.com/packages/sashalenz-novapay-api)
```

###  Alternatives

[dedoc/scramble

Automatic generation of API documentation for Laravel applications.

2.1k11.2M113](/packages/dedoc-scramble)[defstudio/telegraph

A laravel facade to interact with Telegram Bots

813336.8k3](/packages/defstudio-telegraph)[rawilk/profile-filament-plugin

Profile & MFA starter kit for filament.

3914.8k](/packages/rawilk-profile-filament-plugin)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5022.6k](/packages/simplestats-io-laravel-client)[lettermint/lettermint-laravel

Official Lettermint driver for Laravel

1190.2k1](/packages/lettermint-lettermint-laravel)[tarfin-labs/event-machine

Event-driven state machines for Laravel with event sourcing, type-safe context, and full audit trail.

199.4k](/packages/tarfin-labs-event-machine)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)