README

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

vladchornyi / mono

Package info

Security

Statistics