README

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.

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.

Official Documentation

For detailed information about the Monobank Acquiring API, please refer to the official documentation:

Requirements

PHP 8.2+
Laravel 11.0+

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

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

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

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

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

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

Get information about your merchant account.

$details = Monobank::getDetails();
echo $details['merchantName'];

QR Acquiring

You can manage your physical QR stands using the following methods.

1. List QR Registers

$list = Monobank::getQrList();

foreach ($list as $qr) {
    echo $qr->qrId . ' - ' . $qr->pageUrl;
}

2. Get QR Details

$qr = Monobank::getQrDetails('qr_id_here');
echo $qr->shortQrId;

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

Remove the assigned amount from a QR stand.

Monobank::resetQrAmount('qr_id_here');

Recurring Payments (Subscriptions)

You can manage subscriptions for recurring payments.

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

$details = Monobank::getSubscriptionDetails('sub_id_here');

3. Cancel Subscription

Monobank::deleteSubscription('sub_id_here');

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

Retrieve a list of available sub-merchants.

$receivers = Monobank::getSplitReceivers();

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

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

use Illuminate\Support\Facades\Route;

// This registers a POST route that handles signature verification
Route::monobankWebhook('/monobank/webhook');

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
        }
    }
}

Testing

The package is fully tested with Pest. You can run the tests using:

composer test

Testing & Development

To test your integration without real money:

Obtain a Test Acquiring Token from the Monobank Dashboard.
Set this token in your .env file: MONOBANK_TOKEN=your_test_token.
In the test environment, you can use any valid card number (passing Luhn validation) to simulate payments. Financial authorization is skipped.

License

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

aratkruglik / monobank-laravel

Maintainers

Details