maguru/module-mono-core

Monobank Integration Core Module for Magento 2 — HTTP client, config, ECDSA webhook verification

1.0.2 2026-06-26 13:31 UTC

Requires

• php: ~8.1.0||~8.2.0||~8.3.0||~8.4.0||~8.5.0
• ext-json: *
• ext-openssl: *
• guzzlehttp/guzzle: ^7.5
• magento/framework: >=102.0.0
• maguru/magento2-core: ^1.0.1

Suggests

• maguru/module-mono-chast: Monobank BNPL 'Частинами' payment method
• maguru/module-mono-fiscal: Monobank ПРРО fiscal receipts
• maguru/module-mono-payment: Monobank Acquiring payment gateway

proprietary

• Andrii Zakharchuk

Published on Packagist.org on 2026-06-26 13:32 UTC

README

FREE infrastructure module. Provides the shared HTTP clients, encrypted configuration, ECDSA webhook verification, and exception hierarchy used by all other MaGuru Monobank modules.

Requirements

Component	Version
Magento Open Source / Adobe Commerce	2.4.4+
PHP	8.1–8.5
MaGuru_Core	^1.0.1
ext-openssl	any
ext-json	any
guzzlehttp/guzzle	^7.5

Installation

composer require maguru/module-mono-core
bin/magento module:enable MaGuru_MonoCore
bin/magento setup:upgrade
bin/magento cache:flush

Configuration

Stores → Configuration → MaGuru → Monobank Integration

Field	Description
Enabled	Enable/disable the integration
HTTP Timeout	Guzzle request timeout in seconds (default: 15)
Connect Timeout	TCP connect timeout in seconds (default: 5)
Debug Logging	Write detailed request/response logs to var/log/mono_core.log

Acquiring API Token, Chast Store ID and Chast Secret are configured in the same admin section but are contributed by MaGuru_MonoPayment and MaGuru_MonoChast respectively — see their READMEs. They only appear once the corresponding module is installed.

Features

• AcquiringClient — Guzzle HTTP client for api.monobank.ua with X-Token auth and error mapping (403→AuthException, 404→NotFoundException, 429→RateLimitException, 500→ApiException)
• ChastClient — Guzzle HTTP client for Monobank Частини API with HMAC-SHA256 signature header
• WebhookVerifier — ECDSA P-256 / SHA-256 verification of X-Sign webhook signatures with pubkey caching and auto-retry on key rotation
• CLI — bin/magento mono:acquiring:validate-token to verify your API token
• Exception hierarchy — ApiException, AuthException, RateLimitException, NotFoundException

Developer Notes

This module provides interfaces only — no UI, no payment method.

Other modules interact via:

// In di.xml
<preference for="MaGuru\MonoCore\Api\AcquiringClientInterface"
            type="MaGuru\MonoCore\Model\Client\AcquiringClient"/>

Inject AcquiringClientInterface or ChastClientInterface in your service — never instantiate clients directly.

Tests

bin/clinotty php vendor/bin/phpunit -c app/code/MaGuru/MonoCore/Test/Unit/phpunit.xml

57 unit tests · PHPStan Level 8 ✅

Support

• Email: [e-mail]
• Issues: via Magento Marketplace order page

License

Free to use. See LICENSE.txt for details.