Documentation

Quick start

Quick start new Architecture Gateways HTTP API Prepayment and rules Fiscal receipts Notifications and CRM Payment links Analytics new Poland Native Shopify gateway Security new

🆕 What’s new all releases →

v0.18.0 2026-11-01 System health, live checks for all 13 gateways, fee rules, OpenAPI, Docker, extension E2E major release

🩺 “Health” page: process, DB, disk, backups, webhooks, queues, receipts, per-PSP 24 h + live latency; Telegram /health; a watchdog posts when critical and when recovered
🧭 Wizard and health probe all 13 gateways live (monoparts, privatparts, NovaPay, P24, PayU, Tranzzo, RozetkaPay, Portmone added)
💸 FEE_RULES: fee rates by provider × country × currency × amount (+ fixed), fees by market in analytics
📜 OpenAPI 3.1 (/openapi.yaml, 88 routes) + Postman collection
🐳 Docker: Dockerfile + docker compose with Caddy and backups
🧪 E2E test of the Checkout extensions in Chromium against the local server (64 checks); found and fixed a city-selection bug in NP-pickup
🔧 Admin tabs wrap to two rows on desktop

v0.17.1 2026-11-01 Admin tabs

Desktop tabs wrap to a second row instead of being cut off; on phones they scroll with a gradient hint and the active tab is brought into view

v0.17.0 2026-11-01 Setup wizard, webhook inspector, security panel, backup restore major release

🧭 Setup wizard: live checks of Shopify, every PSP, Telegram, SMTP, Nova Poshta, CRM, PRRO and backups — each with a hint naming the key to fix
📥 Webhook inspector: every incoming webhook with its signature result, order, reply and body; filters and “replay”
🛡️ Security panel: failed logins, locked IPs with unlock, active sessions with per-session or all-at-once revoke
💾 ops/restore.sh: restore from a backup with integrity checks; weekly verification of every backup with a Telegram alarm
🧩 extension/setup.sh: the Partner app with all 4 extensions in one command (+ --check)

v0.16.0 2026-11-01 Buyer emails, daily reconciliation, Shopify Markets, line-item return receipts major release

✉️ Buyer emails: “payment received” with items and the receipt, a separate PRRO receipt email, a refund email (uk/ru/en)
🧮 Daily Shopify ↔ Mistok ↔ PSP reconciliation: lost webhooks heal themselves, discrepancies go to Telegram; “Reconcile” button in the admin
🌍 Shopify Markets: charge in the buyer currency where the gateway supports it, else in UAH; recorded in Shopify in the order currency
🧾 Return receipts from the real line items, scaled to the refunded sum
Apple Pay / Google Pay button on the Thank-you page; installment schedule “from ₴X/mo” under the buttons and in the SMS reminder
📱 Mobile admin, 💾 settings export/import, 🧪 one-click “Test purchase”

v0.15.0 2026-11-01 Discount codes in analytics, accounting export, offer & pricing pages, multi-store major release

🎟️ Discount codes in analytics: orders, paid, conversion, AOV and discount amount per code; margin insights
📒 Monthly accounting XLSX: payments, refunds, receipts, per-provider totals with fees (button on the Payments page)
📄 Site: public offer, privacy policy, pricing, request form → Telegram + “Leads” section in the admin
🏪 Several stores on one server: INSTANCE=shop2 PORT=3001 DOMAIN=… — separate database, secrets, service, backups, domain
💳 Stripe: actual fee from balance_transaction

An hour on a test store, another hour for the live token and domain.

mono test token: api.monobank.ua → “Create test token”.The live token is in the plata by mono account once your acquiring agreement is signed.
Shopify → Settings → Payments → Manual payment methods → Create custom → plata by mono.If needed, add “Покупка частинами mono” (mono installments), “Оплата частинами ПриватБанк” (PrivatBank installments), “Przelewy24”, “PayU”, “Stripe”, “Накладений платіж + передоплата” (COD + prepayment).
Settings → Apps and sales channels → Develop apps → an app with scopes read_orders, write_orders (for payment links also read_draft_orders, write_draft_orders).Copy the Admin API access token and the API secret key.
git clone … && cd server && cp .env.example .env — fill in BASE_URL, SHOPIFY_*, MONO_TOKEN, ADMIN_KEY.
npm i && npm test && npm start or docker compose up -d.Locally: ngrok http 3000 → put the address into BASE_URL. Shopify webhooks are registered automatically.
shopify app init → “Build an extension-only app”.
shopify app generate extension --template checkout_ui --flavor preact --name mistok-thank-you → replace src/Checkout.jsx and the targeting/settings sections in the toml with ours from extension/mistok-thank-you.
shopify app generate extension --template customer_account_ui --flavor preact --name mistok-order-status → replace with the files from extension/mistok-order-status (network_access = true).
shopify app dev → shopify app deploy → install the app in the store.
Settings → Checkout → Customize → Thank you → Add block → in the block settings set pay_base_url = your BASE_URL, providers = mono,monoparts. Same on Order status.
(optional) Paste extension/email-snippet.liquid into Settings → Notifications → Order confirmation — the payment link will also be in the email.
Test: order → “plata by mono” → button on the Thank you page → test payment → order Paid, tags mistok-paid, mono:<id>; Order status shows “Paid”.
Test: Refund in the admin → refund in the mono account. Cancel → invoice voided. Open /admin/dashboard?key=….
Production: live token, TRUST_PROXY=1 behind nginx/Cloudflare, HTTPS, FISCAL_MODE, Telegram, SMTP.

Setup wizard, one-command Partner app, restore new

Admin → 🧭 Wizard (“Check”) — live, read-only checks of every .env key: Shopify (shop, plan, currency, registered webhooks), mono (/api/merchant/details), Stripe (balance), LiqPay / WayForPay / Fondy (status probe for a non-existent order proves the keys without a payment), Telegram (getMe + chat), SMTP (verify), Nova Poshta, CRM, PRRO, backups. Every failure comes with a hint naming the key to fix. JSON: GET /admin/api/setup?run=1.
Partner app in one command: bash extension/setup.sh --store my-store.myshopify.com --base-url https://pay.example.com assembles all 4 extensions into extension/app/extensions/, installs dependencies, writes SETTINGS.md with the values for the checkout/theme editor and leaves two final steps: shopify app dev, shopify app deploy. --check only validates toml/JSX.
Restore from a backup: bash /opt/mistok/ops/restore.sh (list), … latest --yes (newest), … --verify (checks every backup: gzip + integrity_check; the mistok-backup-verify timer runs it weekly and alerts Telegram on failure). The current database is kept as pre-restore-* before the swap.

Docker: cp server/.env.example mistok.env (strip the comments, see ops/docker.md) → DOMAIN=pay.example.com docker compose up -d — Mistok + Caddy (HTTPS) + backups every 4 h. The image builds from the repo root (Dockerfile).
API spec: /openapi.yaml (OpenAPI 3.1, every public and admin route, webhook schemas) and /postman_collection.json — for integrators.
Extension E2E test: npm run test:e2e renders the real Thank-you / Order status / NP-pickup blocks in Chromium against the local server (64 checks, ~15 s) — no dev store needed.

All you need for live mode is your acquiring agreement with a bank/PSP. Mistok is not a party to the payment.