PHPackages aratkruglik/monobank-laravel - 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. aratkruglik/monobank-laravel ActiveLibrary[API Development](/categories/api) aratkruglik/monobank-laravel ============================ A comprehensive Monobank API integration for Laravel 11, 12, 13 1.1.1(3mo ago)6124MITPHPPHP ^8.3 Since Jan 12Pushed 3mo agoCompare [ Source](https://github.com/AratKruglik/monobank-acquiring-laravel)[ Packagist](https://packagist.org/packages/aratkruglik/monobank-laravel)[ RSS](/packages/aratkruglik-monobank-laravel/feed)WikiDiscussions main Synced today READMEChangelog (3)Dependencies (10)Versions (6)Used By (0) Monobank Acquiring for Laravel ============================== [](#monobank-acquiring-for-laravel) A robust, idiomatic Laravel package for integrating with the **Monobank Acquiring API**. Designed specifically for e-commerce applications, it provides secure invoice creation, payment processing, refund handling, and webhook verification. [![Latest Version on Packagist](https://camo.githubusercontent.com/dfc4bc4ec5f2fe4a2cb85aa3c5d162783bb3ff7e699e8f3d0cef8000bcdaa1e5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f617261746b7275676c696b2f6d6f6e6f62616e6b2d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/aratkruglik/monobank-laravel)[![Tests](https://github.com/aratkruglik/monobank-laravel/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/aratkruglik/monobank-laravel/actions/workflows/run-tests.yml)[![Total Downloads](https://camo.githubusercontent.com/44e1814f9c9dd2ce26730b7f7224d9f8f84e24a8e5ce907dd09965ceef7d614d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f617261746b7275676c696b2f6d6f6e6f62616e6b2d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/aratkruglik/monobank-laravel) Features -------- [](#features) - 🚀 **Full Acquiring API Support**: Create invoices, check statuses, process refunds. - 🔒 **Security First**: Automatic verification of Monobank Webhook signatures (ECDSA) using dynamic Public Key caching. - 📦 **Strictly Typed**: Uses DTOs and Enums for all requests and responses. No magic arrays. - ⚡ **Laravel Native**: Integration with Laravel's Event system, HTTP Client, and Service Container. - 🛡️ **Security Hardened**: User-friendly error messages that don't expose API internals, sanitized logging, input validation. Official Documentation ---------------------- [](#official-documentation) For detailed information about the Monobank Acquiring API, please refer to the official documentation: - [Internet Acquiring API](https://monobank.ua/api-docs/acquiring) - [QR Acquiring API](https://monobank.ua/api-docs/acquiring/methods/qr/post--api--merchant--invoice--create) - [Recurring Payments API](https://monobank.ua/api-docs/acquiring/methods/subscription/post--api--merchant--subscription--create) - [Marketplace / Split Payments API](https://monobank.ua/api-docs/acquiring/methods/split/post--api--merchant--invoice--create) Requirements ------------ [](#requirements) - PHP 8.3+ - Laravel 11.x-13.x Installation ------------ [](#installation) You can install the package via composer: ``` composer require aratkruglik/monobank-laravel ``` Publish the configuration file: ``` php artisan vendor:publish --tag="monobank-config" ``` Configuration ------------- [](#configuration) Add your Monobank Acquiring Token (X-Token) to your `.env` file: ``` MONOBANK_TOKEN=your_token_here MONOBANK_REDIRECT_URL=https://your-site.com/checkout/success MONOBANK_WEBHOOK_URL=https://your-site.com/api/monobank/webhook ``` You can customize the configuration in `config/monobank.php`. Usage ----- [](#usage) ### 1. Creating an Invoice [](#1-creating-an-invoice) To accept a payment, create an invoice. You can pass the amount as **float** (major units, e.g., `100.50` UAH) or **integer** (cents, e.g., `10050`). ``` use AratKruglik\Monobank\Facades\Monobank; use AratKruglik\Monobank\DTO\InvoiceRequestDTO; use AratKruglik\Monobank\Enums\CurrencyCode; $invoice = Monobank::createInvoice(new InvoiceRequestDTO( amount: 100.00, // 100.00 UAH ccy: CurrencyCode::UAH, destination: 'Payment for Order #12345', reference: 'ORDER-12345', redirectUrl: 'https://myshop.com/thank-you', successUrl: 'https://myshop.com/success', failUrl: 'https://myshop.com/failure', webHookUrl: 'https://myshop.com/api/webhook', validity: 3600 // 1 hour )); // Redirect user to the payment page return redirect($invoice->pageUrl); ``` #### With Cart Items [](#with-cart-items) You can pass detailed cart information for the fiscal check. ``` use AratKruglik\Monobank\DTO\CartItemDTO; $cart = [ new CartItemDTO(name: 'T-Shirt', qty: 2, sum: 50.00, code: 'tshirt-001'), // 50.00 UAH new CartItemDTO(name: 'Socks', qty: 1, sum: 2.00, code: 'socks-001'), // 2.00 UAH ]; $request = new InvoiceRequestDTO( amount: 102.00, // Total: 102.00 UAH cartItems: $cart ); $invoice = Monobank::createInvoice($request); ``` ### 2. Checking Invoice Status [](#2-checking-invoice-status) Retrieve the current status of an invoice. The response uses strict Enums. ``` use AratKruglik\Monobank\Enums\InvoiceStatus; $status = Monobank::getInvoiceStatus('invoice_id_here'); if ($status->status === InvoiceStatus::SUCCESS) { // Order paid! } elseif ($status->status === InvoiceStatus::FAILURE) { // Payment failed } ``` ### 3. Cancelling / Refunding [](#3-cancelling--refunding) You can cancel an unpaid invoice or refund a paid one (fully or partially). ``` // Full refund / Cancel Monobank::cancelInvoice('invoice_id_here'); // Partial refund (e.g., refunding 50.50 UAH) Monobank::cancelInvoice( invoiceId: 'invoice_id_here', amount: 50.50 // 50.50 UAH ); ``` ### 4. Merchant Details [](#4-merchant-details) Get information about your merchant account. ``` $details = Monobank::getDetails(); echo $details['merchantName']; ``` QR Acquiring ------------ [](#qr-acquiring) You can manage your physical QR stands using the following methods. ### 1. List QR Registers [](#1-list-qr-registers) ``` $list = Monobank::getQrList(); foreach ($list as $qr) { echo $qr->qrId . ' - ' . $qr->pageUrl; } ``` ### 2. Get QR Details [](#2-get-qr-details) ``` $qr = Monobank::getQrDetails('qr_id_here'); echo $qr->shortQrId; ``` ### 3. Invoice for QR Stand [](#3-invoice-for-qr-stand) To assign an amount to a specific QR stand (so the client scans it and sees the amount), create an invoice passing the `qrId`. ``` $invoice = Monobank::createInvoice(new InvoiceRequestDTO( amount: 150.00, qrId: 'qr_id_here' )); ``` ### 4. Reset QR Amount [](#4-reset-qr-amount) Remove the assigned amount from a QR stand. ``` Monobank::resetQrAmount('qr_id_here'); ``` Recurring Payments (Subscriptions) ---------------------------------- [](#recurring-payments-subscriptions) You can manage subscriptions for recurring payments. ### 1. Create Subscription [](#1-create-subscription) ``` use AratKruglik\Monobank\DTO\SubscriptionRequestDTO; $subscription = Monobank::createSubscription(new SubscriptionRequestDTO( amount: 100.00, // 100.00 UAH interval: '1m', // 1 month webHookStatusUrl: 'https://site.com/sub/status', redirectUrl: 'https://site.com/thank-you' )); return redirect($subscription->pageUrl); ``` ### 2. Get Subscription Details [](#2-get-subscription-details) ``` $details = Monobank::getSubscriptionDetails('sub_id_here'); ``` ### 3. Cancel Subscription [](#3-cancel-subscription) ``` Monobank::deleteSubscription('sub_id_here'); ``` Marketplace / Split Payments ---------------------------- [](#marketplace--split-payments) You can split a payment between multiple recipients (sub-merchants) by specifying `splitReceiverId` for each item in the cart. ### 1. Get Split Receivers [](#1-get-split-receivers) Retrieve a list of available sub-merchants. ``` $receivers = Monobank::getSplitReceivers(); ``` ### 2. Create Split Invoice [](#2-create-split-invoice) ``` use AratKruglik\Monobank\DTO\CartItemDTO; $cart = [ new CartItemDTO( name: 'Item from Partner A', qty: 1, sum: 100.00, splitReceiverId: 'receiver_id_a' ), new CartItemDTO( name: 'Item from Partner B', qty: 1, sum: 200.00, splitReceiverId: 'receiver_id_b' ), ]; $request = new InvoiceRequestDTO( amount: 300.00, cartItems: $cart ); $invoice = Monobank::createInvoice($request); ``` Webhooks -------- [](#webhooks) This package handles webhook security automatically. It fetches Monobank's public key, caches it, and verifies the `X-Sign` header for every incoming request. ### 1. Setup Route [](#1-setup-route) Register the webhook route in your `routes/api.php` using the provided macro: ``` use Illuminate\Support\Facades\Route; // This registers a POST route that handles signature verification Route::monobankWebhook('/monobank/webhook'); ``` ### 2. Handle Events [](#2-handle-events) When a valid webhook is received, the package dispatches the `AratKruglik\Monobank\Events\WebhookReceived` event. You should listen for this event in your application. **EventServiceProvider:** ``` use AratKruglik\Monobank\Events\WebhookReceived; use App\Listeners\HandleMonobankPayment; protected $listen = [ WebhookReceived::class => [ HandleMonobankPayment::class, ], ]; ``` **Listener:** ``` namespace App\Listeners; use AratKruglik\Monobank\Events\WebhookReceived; use AratKruglik\Monobank\Enums\InvoiceStatus; class HandleMonobankPayment { public function handle(WebhookReceived $event): void { $payload = $event->payload; // $payload is an array containing invoiceId, status, amount, etc. $invoiceId = $payload['invoiceId']; $status = $payload['status']; if ($status === InvoiceStatus::SUCCESS->value) { // Mark order as paid } } } ``` Error Handling -------------- [](#error-handling) The package provides typed exceptions with user-friendly messages that don't expose sensitive API details: ``` use AratKruglik\Monobank\Exceptions\ValidationException; use AratKruglik\Monobank\Exceptions\AuthenticationException; use AratKruglik\Monobank\Exceptions\RateLimitExceededException; use AratKruglik\Monobank\Exceptions\ServerException; try { $invoice = Monobank::createInvoice($request); } catch (ValidationException $e) { // User-friendly message for display $userMessage = $e->getMessage(); // "Payment validation failed..." // API details for logging (not exposed to users) Log::error('Monobank error', $e->getApiErrorDetails()); } catch (RateLimitExceededException $e) { // Retry after the specified time $retryAfter = $e->retryAfter; // seconds } catch (AuthenticationException $e) { // Check your API token } ``` Testing ------- [](#testing) The package is fully tested with **Pest**. You can run the tests using: ``` composer test ``` Testing & Development ------------------------- [](#testing--development) To test your integration without real money: 1. Obtain a **Test Acquiring Token** from the [Monobank Dashboard](https://web.monobank.ua/). 2. Set this token in your `.env` file: `MONOBANK_TOKEN=your_test_token`. 3. In the test environment, you can use any valid card number (passing Luhn validation) to simulate payments. Financial authorization is skipped. License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 43 — FairBetter than 89% of packages Maintenance82 Actively maintained with recent releases Popularity18 Limited adoption so far Community6 Small or concentrated contributor base Maturity53 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 ~38 days Total 3 Last Release 95d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/9255774?v=4)[Oleksii Kruhlyk](/maintainers/AratKruglik)[@AratKruglik](https://github.com/AratKruglik) --- Top Contributors [![AratKruglik](https://avatars.githubusercontent.com/u/9255774?v=4)](https://github.com/AratKruglik "AratKruglik (11 commits)") --- Tags apilaravelfinanceBankingmonobank ### Code Quality TestsPest ### Embed Badge ![Health badge](/badges/aratkruglik-monobank-laravel/health.svg) ``` [![Health](https://phpackages.com/badges/aratkruglik-monobank-laravel/health.svg)](https://phpackages.com/packages/aratkruglik-monobank-laravel) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3355.3M346](/packages/psalm-plugin-laravel)[defstudio/telegraph A laravel facade to interact with Telegram Bots 816333.6k3](/packages/defstudio-telegraph)[api-platform/laravel API Platform support for Laravel 58171.4k14](/packages/api-platform-laravel)[resend/resend-laravel Resend for Laravel 1222.7M9](/packages/resend-resend-laravel)[essa/api-tool-kit set of tools to build an api with laravel 53390.0k](/packages/essa-api-tool-kit)[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. 5021.9k](/packages/simplestats-io-laravel-client) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)