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

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
Acquiring API Token	Your Monobank merchant X-Token (encrypted)
Chast Store ID	Store ID for Monobank Частини API
Chast Secret	HMAC-SHA256 secret for Chast callbacks (encrypted)
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

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.