Download the PHP package rilong/monobank-installments without Composer

monobank-installments

🇺🇦 Українська версія нижче

💳 A Laravel package for integrating Monobank Parts installment payments into your application — create orders, track their state, confirm delivery, handle returns, and more.

Let your customers pay in installments via Monobank while keeping your integration clean and fully typed. Every request is automatically signed with HMAC-SHA256, all inputs and outputs are readonly DTOs, and the entire API surface is available through a single Laravel Facade.

Features:

• 🔐 Automatic HMAC-SHA256 request signing — no manual auth setup
• 📦 Fully typed DTOs for all inputs and responses
• 🏪 Facade + service container support
• ⚡ Works with Laravel's package auto-discovery
• 🔄 Full order lifecycle: create → confirm → return
• 🧪 Tested with Pest + Orchestra Workbench

Requirements

• PHP 8.2+
• Laravel 12 or 13

Installation

The service provider and facade are registered automatically via Laravel's package discovery.

Configuration

Call MonobankInstallments::configure() before making any API calls — typically in a service provider's boot() method or in your application's bootstrap code.

Option 1 — via .env:

Add credentials to your .env:

Then configure in AppServiceProvider::boot():

Option 2 — via a config file:

Create a config file (e.g. config/monobank.php):

Then configure using it:

Usage

All methods are available via the facade:

Create order

Initiates a new installment order for a client. Returns an orderId that you use in all subsequent calls for this order.

CreateOrderDTO fields:

InvoiceDTO fields:

Get order state

Returns the current state of an order. Poll this endpoint after order creation to track the client's progress through the installment flow.

Confirm order

Confirms the order on the store side. Call this once the order has been shipped to the client. Returns an OrderResponse with the updated state.

Cancel order

Rejects an open order before it is confirmed (i.e. before shipment). Use this if the client changes their mind or the goods are no longer available. Returns an OrderResponse with the updated state.

Return order

Creates a full or partial return for a previously confirmed order. ReturnMoneyTo::Card sends the refund to the client's card; ReturnMoneyTo::Cash marks it as a cash refund.

Get order data

Fetches full information about an order including return history. Useful for reconciling operations, displaying order status in a client dashboard, analytics, reporting, and processing returns.

Returns:

• Basic order data (amount, status, dates)
• Client information
• Installment details (number of payments, amounts)
• Full return history with dates and amounts
• Current outstanding balance

Check paid status

Checks whether the client has fully paid off their installments, and whether the bank can issue a card refund if a return is needed.

Response types

All response classes implement JsonSerializable and __toString().

OrderResponse

OrderResponse is returned by getState(), confirmOrder(), and cancelOrder(). It represents the current state of an order at the time of the call.

Tip: Always branch on orderSubState, not state. Two orders can share the same state (e.g. FAIL) but require different handling depending on the sub-state.

Order states

OrderState

OrderSubState

Exceptions

All API errors throw Rilong\MonobankInstallments\Exceptions\MonobankInstallmentsException, which exposes a statusCode property alongside the standard exception message.

License

MIT

monobank-installments (Українська)

💳 Laravel-пакет для інтеграції Monobank оплати частинами (оплата частинами) у ваш застосунок — створюйте заявки, відстежуйте їх статус, підтверджуйте доставку, обробляйте повернення та багато іншого.

Дозвольте вашим клієнтам платити частинами через Monobank, зберігаючи інтеграцію чистою та повністю типізованою. Кожен запит автоматично підписується за допомогою HMAC-SHA256, всі вхідні та вихідні дані — readonly DTO, а весь API доступний через єдиний Laravel Facade.

Можливості:

• 🔐 Автоматичне підписування запитів HMAC-SHA256 — без ручного налаштування авторизації
• 📦 Повністю типізовані DTO для всіх вхідних і вихідних даних
• 🏪 Підтримка Facade + service container
• ⚡ Працює з автовідкриттям пакетів Laravel
• 🔄 Повний життєвий цикл заявки: створення → підтвердження → повернення
• 🧪 Протестовано з Pest + Orchestra Workbench

Вимоги

• PHP 8.2+
• Laravel 12 або 13

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

Сервіс-провайдер та фасад реєструються автоматично через механізм автовідкриття пакетів Laravel.

Налаштування

Викличте MonobankInstallments::configure() перед будь-якими API-запитами — зазвичай у методі boot() сервіс-провайдера або під час завантаження застосунку.

Варіант 1 — через .env:

Додайте облікові дані до .env:

Потім налаштуйте у AppServiceProvider::boot():

Варіант 2 — через файл конфігурації:

Створіть файл конфігурації (наприклад, config/monobank.php):

Потім використайте його:

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

Всі методи доступні через фасад:

Створення заявки

Ініціює нову заявку на оплату частинами для клієнта. Повертає orderId, який використовується у всіх наступних запитах для цієї заявки.

Поля CreateOrderDTO:

Поля InvoiceDTO:

Отримання статусу заявки

Повертає поточний статус заявки. Опитуйте цей метод після створення заявки для відстеження прогресу клієнта.

Підтвердження заявки

Підтверджує заявку зі сторони магазину. Викликайте після відправки товару клієнту. Повертає OrderResponse з оновленим статусом.

Скасування заявки

Відхиляє відкриту заявку до її підтвердження (тобто до відправки товару). Використовуйте, якщо клієнт передумав або товар недоступний. Повертає OrderResponse з оновленим статусом.

Повернення заявки

Створює повне або часткове повернення для раніше підтвердженої заявки. ReturnMoneyTo::Card — повернення на картку клієнта; ReturnMoneyTo::Cash — готівкове повернення.

Отримання даних заявки

Отримує повну інформацію про заявку, включаючи історію повернень. Корисно для звірки операцій, відображення статусу в особистому кабінеті, аналітики, звітності та обробки повернень.

Повертає:

• Базові дані заявки (сума, статус, дати)
• Інформацію про клієнта
• Деталі ПЧ (кількість платежів, суми)
• Повну історію повернень з датами та сумами
• Поточний залишок заборгованості

Перевірка статусу оплати

Перевіряє, чи клієнт повністю погасив розстрочку, та чи може банк повернути кошти на картку у разі повернення.

Типи відповідей

Всі класи відповідей реалізують JsonSerializable та __toString().

OrderResponse

OrderResponse повертається методами getState(), confirmOrder() та cancelOrder(). Представляє поточний стан заявки на момент виклику.

Порада: Завжди перевіряйте orderSubState, а не state. Дві заявки можуть мати однаковий state (наприклад, FAIL), але потребувати різної обробки залежно від підстатусу.

Статуси заявки

OrderState

OrderSubState

Винятки

Всі API-помилки генерують Rilong\MonobankInstallments\Exceptions\MonobankInstallmentsException, який містить властивість statusCode поряд зі стандартним повідомленням про помилку.

Ліцензія

MIT