Monobank Acquiring PHP Client

PHP client for the Monobank Acquiring API: invoices, subscriptions, statements, merchant details, webhook signature verification, and structured error handling.

Features

• Invoices: create, status, cancel, invalidate, hold finalization, receipts, and fiscal checks.
• Subscriptions: create, status, list, payment history, cancel with refund, remove.
• Tokenized cards: wallet listing, payment by card token, card deletion.
• Statements, merchant details, submerchants, and split receivers.
• Verified webhook parsing with X-Sign support.
• Typed webhook payload helpers for invoice and subscription events.
• Versioned webhook deduplication and stale-event protection via modifiedDate.
• Rotation-aware public-key verification with injectable shared caching.
• Replaceable HTTP layer for tests and framework integrations.
• Response-header capture and safe retry handling for idempotent requests.
• Structured exceptions and safe logging helpers.

Version 2.0 contains intentional breaking changes. Existing 1.x applications should follow the upgrade guide before changing the constraint.

Requirements

• PHP 8.0+
• ext-json
• ext-mbstring
• ext-curl when using the default CurlHttpClient.
• ext-openssl when using built-in webhook verification.

Installation

composer require vladchornyi/mono:^2.0

Quick Start

use Vladchornyi\Mono\Models\InvoiceData;
use Vladchornyi\Mono\MonoClient;

$mono = new MonoClient($_ENV['MONO_KEY']);

// 1. Create the invoice and send the customer to pageUrl.
$invoice = $mono->invoices()->createInvoice(new InvoiceData(
    amount: 58000,                                       // kopecks
    redirectUrl: 'https://example.com/payments/return',
    webHookUrl: 'https://example.com/webhooks/monobank'
));
header('Location: ' . $invoice['pageUrl']);

// 2. In the webhook endpoint: verify the signature, then apply the status.
$event = $mono->webhooks()->parseVerifiedPayload(
    file_get_contents('php://input'),
    $_SERVER['HTTP_X_SIGN'] ?? null
);

if ($event->isSuccessful()) {
    // mark the order paid, once per $event->deduplicationKey()
}

The complete walk-through, including stale-event and duplicate handling, is in Getting Started.

Documentation

• Getting started: first payment
• Installation and client setup
• Invoices, one complete example per capability
• API coverage
• Webhooks and the transactional handler example in examples/Webhooks
• Subscriptions
• Statements and merchant details
• Errors and safe logging
• Upgrade notes

Testing From Source

composer install
composer test
composer test:ci
composer analyse
composer cs

The default test suite is self-contained and does not call Monobank. It includes four release-gate suites, also runnable alone with composer test:release:

• tests/Contract: every SDK request is checked against the Monobank OpenAPI document stored in tests/fixtures/monobank (method, path, documented fields, JSON lists, required fields, query parameters); responses built from the specification's examples must be readable by the SDK.
• tests/Migration: real 1.x call forms executed against 2.0, the evidence behind UPGRADING.md.
• tests/Regression: one reproduction per defect found during the 2.0 review.
• tests/Docs: every PHP block in the docs compiles, every documented client call exists, and docs/api-coverage.md lists every specification endpoint.

For an optional live smoke test, set MONO_KEY or MONO_ENV_FILE:

MONO_KEY=... composer test:live
MONO_ENV_FILE=/path/to/.env composer test:live

To verify live invoice and subscription creation with a test merchant key:

MONO_KEY=... MONO_LIVE_CREATE_CONFIRM=yes composer test:live-create
MONO_ENV_FILE=/path/to/.env MONO_LIVE_CREATE_CONFIRM=yes composer test:live-create

The live create smoke test uses a minimal amount and attempts cleanup after creation. Set MONO_LIVE_CREATE_CLEANUP=false only when you intentionally want to retain the created test resources.

License

MIT