plata by mono Ukraine
Cards, Apple Pay, Google Pay, hold, split, QR cash register. Official documentation: https://monobank.ua/api-docs/acquiring. Gateway fee: 1.3% UA cards / 2% foreign cards (mono rate).
Credentials
Test token — the “Create test token” button on api.monobank.ua. Live token — in the plata by mono account once the acquiring agreement is signed. The token is sent in the X-Token header.
- Environment variables
MONO_TOKENMONO_WEBHOOK_SECRET (optional)PAYMENT_TYPE=debit|holdSPLIT_RECEIVERS (optional)QR_VALIDITY_SEC=900 (opt.)- Webhook
POST /webhooks/mono[/<secret>]. HeaderX-Sign= base64(ECDSA-SHA256(body)). Verified with mono’s public key; the webhook body is not the source of truth — the status is re-read from the API.
What Mistok calls
| Request | Fields / meaning |
|---|---|
POST /api/merchant/invoice/create | amount (kopiykas), ccy (980/840/978), merchantPaymInfo{reference=#1001, destination, customerEmails, basketOrder[{name, qty, sum, code, unit, splitReceiverId?}]}, redirectUrl, webHookUrl, validity, paymentType → {invoiceId, pageUrl} |
GET /api/merchant/invoice/status?invoiceId | status, amount, ccy, failureReason — Mistok re-reads it after every webhook |
POST /api/merchant/invoice/cancel | refund (full/partial): invoiceId, amount, extRef=shopify-refund-<id> |
POST /api/merchant/invoice/finalize | capture of the hold on orders/fulfilled |
POST /api/merchant/invoice/remove | voiding an unpaid invoice (order cancelled/edited) |
GET /api/merchant/invoice/fiscal-checks | PRRO receipts (FISCAL_MODE=mono): id, status, type, taxUrl |
GET /api/merchant/invoice/receipt?email | receipt emailed to the buyer (SEND_MONO_RECEIPT) |
GET /api/merchant/pubkey | public key for webhook verification; cached, re-fetched on an invalid signature no more than once a minute |
GET /api/merchant/qr/list | merchant QR cash registers: qrId, shortQrId, amountType (merchant | client | fix), pageUrl |
GET /api/merchant/qr/details?qrId | what is on the QR now: amount, ccy, invoiceId (only when an amount is set) |
POST /api/merchant/invoice/create + qrId | QR cash register: the same order invoice with a qrId field — the amount appears on the physical QR sticker (showroom, pickup point, pop-up). validity = QR_VALIDITY_SEC (900 s) |
POST /api/merchant/qr/reset-amount | remove the amount from the QR; Mistok also invalidates the invoice (status qr_cleared) |
Statuses
created · processing · hold · success · failure · reversed · expired — used as is (this is Mistok’s base status model).
Mistok’s model: created → processing → (hold →) success | failure | expired | reversed. The Shopify order receives a payment only on success and only after the amount and currency are checked against our record.
Sandbox
The test token creates invoices that can be paid with a test card in the account. Webhooks arrive at your BASE_URL (locally — via ngrok). QR cash registers are created in the plata by mono cabinet (the QR sticker at the till); control from Mistok: admin → “QR cash registers”, Telegram /qr OBJE #1001, /qr clear OBJE, or POST /admin/qr/<qrId>/show {orderId}.
Limitations
- validity ≤ 24 h by default
- product name ≤ 128 characters
- basketOrder is mandatory when a PRRO link is active — amounts must match to the kopiyka