plata by mono Україна
Картки, Apple Pay, Google Pay, hold, split, QR-каса. Офіційна документація: https://monobank.ua/api-docs/acquiring. Комісія шлюзу: 1,3 % картки UA / 2 % іноземні (тариф mono).
Доступи
Тестовий токен — кнопка «Create test token» на api.monobank.ua. Бойовий — у кабінеті plata by mono після договору еквайрингу. Токен передається в заголовку X-Token.
- Змінні середовища
MONO_TOKENMONO_WEBHOOK_SECRET (опц.)PAYMENT_TYPE=debit|holdSPLIT_RECEIVERS (опц.)QR_VALIDITY_SEC=900 (опц.)- Вебхук
POST /webhooks/mono[/<secret>]. ЗаголовокX-Sign= base64(ECDSA-SHA256(тіло)). Перевірка публічним ключем mono; тіло вебхука не є джерелом істини — статус перечитується з API.
Що викликає Місток
| Запит | Поля / сенс |
|---|---|
POST /api/merchant/invoice/create | amount (копійки), 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 — Місток перечитує його після кожного вебхука |
POST /api/merchant/invoice/cancel | повернення (повне/часткове): invoiceId, amount, extRef=shopify-refund-<id> |
POST /api/merchant/invoice/finalize | списання холду при orders/fulfilled |
POST /api/merchant/invoice/remove | анулювання неоплаченого інвойсу (скасування/редагування замовлення) |
GET /api/merchant/invoice/fiscal-checks | чеки ПРРО (FISCAL_MODE=mono): id, status, type, taxUrl |
GET /api/merchant/invoice/receipt?email | квитанція покупцю на email (SEND_MONO_RECEIPT) |
GET /api/merchant/pubkey | публічний ключ для перевірки вебхуків; кешується, перезапит при невалідному підписі не частіше 1 раз/хв |
GET /api/merchant/qr/list | QR-каси мерчанта: qrId, shortQrId, amountType (merchant | client | fix), pageUrl |
GET /api/merchant/qr/details?qrId | що зараз на QR: amount, ccy, invoiceId (тільки якщо сума встановлена) |
POST /api/merchant/invoice/create + qrId | QR-каса: той самий інвойс замовлення, але з полем qrId — сума з’являється на фізичному QR (шоурум, пункт видачі, pop-up). validity = QR_VALIDITY_SEC (900 с) |
POST /api/merchant/qr/reset-amount | зняти суму з QR; Місток також анулює інвойс (статус qr_cleared) |
Статуси
created · processing · hold · success · failure · reversed · expired — використовуються як є (це базова модель статусів Містка).
Модель Містка: created → processing → (hold →) success | failure | expired | reversed. Замовлення в Shopify отримує оплату лише на success і лише після звірки суми й валюти з нашим записом.
Пісочниця
Тестовий токен створює інвойси, які можна оплатити тестовою карткою у кабінеті. Вебхуки приходять на ваш BASE_URL (локально — через ngrok). QR-каси створюються в кабінеті plata by mono (QR-наліпка на касі); керування з Містка: адмінка → «QR-каси», Telegram /qr OBJE #1001, /qr clear OBJE, або POST /admin/qr/<qrId>/show {orderId}.
Обмеження
- validity ≤ 24 год за замовчуванням
- назва товару ≤ 128 символів
- basketOrder обов’язковий при активній зв’язці з ПРРО — суми мають збігатися до копійки