MaGuru MonoFiscal — Monobank ПРРО Fiscal Integration for Magento 2

Automatic Ukrainian ПРРО (Програмний реєстратор розрахункових операцій) fiscal receipt integration via Monobank Acquiring. Fetches, stores, and displays fiscal check links after each successful payment. Supports basket order injection for itemized fiscal receipts, fiscalization on returns, retry of failed checks, and customer email notification.

Scope: listens only to MaGuru_MonoPayment events (mono_payment_invoice_success etc.). Orders paid via MaGuru_MonoChast (installments) are not fiscalized by this module — and don't need to be: Monobank fiscalizes Частинами purchases on their own side.

Running alongside MaGuru_CheckboxFiscal? That module fiscalizes every payment method by default, including monopay — which would double-fiscalize the same sale. In CheckboxFiscal's config, set "Fiscalize Only These Payment Methods" to exclude monopay (leave it out of the selection) so only MonoFiscal handles those orders.

Requires: maguru/module-mono-core + maguru/module-mono-payment

---

Requirements

Component	Version
Magento Open Source / Adobe Commerce	2.4.4+
PHP	8.1+
MaGuru MonoCore	^1.0
MaGuru MonoPayment	^1.0

---

Installation

composer require maguru/module-mono-core maguru/module-mono-payment maguru/module-mono-fiscal
bin/magento module:enable MaGuru_MonoCore MaGuru_MonoPayment MaGuru_MonoFiscal
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

---

Message Queue Setup

Fiscal check fetch is published to Magento's message queue instead of being called synchronously from the payment-success observer. The queue does nothing until a consumer processes it — Magento does not run consumers automatically out of the box.

Consumer	Purpose
mono_fiscal.check.fetch	Fetch fiscal check(s) from Monobank after successful payment

Recommended: register the consumer in app/etc/env.php so Magento's own cron picks it up automatically (no extra process to manage):

'cron_consumers_runner' => [
    'cron_run' => true,
    'max_messages' => 200,
    'consumers' => [
        'mono_fiscal.check.fetch',
    ]
],

Alternative: run a persistent process under supervisor/systemd:

bin/magento queue:consumers:start mono_fiscal.check.fetch

Without one of the above, fiscal checks are never fetched automatically after payment — the "Fiscal Checks" section in the order view stays empty and the customer email never sends, even though the check exists on Monobank/Checkbox's side. Use the Fetch Checks button in the admin order view (calls the API synchronously) to retrieve checks manually while the queue is unconfigured.

---

Configuration

Stores → Configuration → MaGuru → Monobank Fiscal (ПРРО)

Field	Description
Enabled	Enable/disable fiscal integration
Send Basket Order	Include itemized product list (basketOrder) in invoice for ПРРО receipts
Email Fiscal Check	Send customer an email with the fiscal receipt link (taxUrl) after payment
Checkbox Tax Rate IDs	Comma-separated Checkbox ПРРО tax rate integer IDs applied to all basket items by default (e.g. 1 or 1,2). Not a VAT percentage — an ID assigned by Checkbox for your merchant account; get it from your Monobank acquiring manager
Per-Product Tax Rate Attribute	Product attribute code holding comma-separated tax rate IDs for that specific product. Falls back to Checkbox Tax Rate IDs when empty for a product. Use for catalogs with mixed VAT rates
UKTZED Attribute	Product attribute code holding the УКТЗЕД commodity code, if required for your product categories

---

Features

Automatic Fiscal Check Fetch

• After every successful Monobank payment, calls GET /api/merchant/invoice/fiscal-checks
• Saves check ID, status, type, source (Checkbox/MonoPay), tax URL, and PDF (base64) to mono_fiscal_check table
• Upsert logic — safe to re-run; existing checks are updated, not duplicated

Basket Order Injection (Itemized ПРРО)

• Injects basketOrder[] into the invoice payload at creation time
• Each item: {name, qty, sum (kopecks), code (SKU), unit, tax[]}
• Activates only when Send Basket Order is enabled
• Tax rate per item resolves from Per-Product Tax Rate Attribute first, falling back to Checkbox Tax Rate IDs when the product's attribute is empty — supports catalogs with mixed VAT rates

Fiscalization on Returns (Credit Memo)

• Injects items[] into the cancel/refund payload
• Allows Monobank to issue ПРРО return receipts automatically

Customer Email Notification

• After payment success, sends customer an email with a link to their fiscal receipt on the DPS (ДПС) portal
• Template: Monobank Fiscal Check Notification — customizable in Marketing → Email Templates
• Fail-safe: email errors are logged but do not affect payment processing

Retry Failed Checks

• Cron runs every 6 hours, finds checks with status = failed, re-fetches from Monobank
• Handles transient API failures without manual intervention

Admin Grid

• System → Monobank → Fiscal Checks — all fiscal checks with status, type, source, tax URL link
• Filter by status, invoice ID, date range; CSV export
• Per-row actions: Download PDF and View on DPS

Order View Block

• Fiscal checks table embedded in the Magento admin order view
• Shows check ID, status, type, source, direct link to ДПС receipt, and a Download PDF link

---

REST API

GET  /V1/mono/fiscal/order/:orderId/checks          [admin]  — get fiscal checks for an order
POST /V1/mono/fiscal/invoice/:invoiceId/fetch       [admin]  — manually trigger fetch for an invoice

---

How It Works

Payment success
    → mono_payment_invoice_success event
        → FetchFiscalCheckAfterSuccess  (1st observer)
              GET /api/merchant/invoice/fiscal-checks
              → upsert mono_fiscal_check
        → EmailFiscalCheckAfterSuccess  (2nd observer, runs after fetch)
              find taxUrl in mono_fiscal_check
              → send email to customer

---

Tests

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

94 unit tests · 148 assertions · PHPStan Level 8 ✅

---

Support

• Email: maguru.sup@gmail.com
• Issues: via Magento Marketplace order page

---

License

Proprietary — one-time license per domain