Що саме треба зв'язати
Ланцюжок виглядає так: сайт створює рахунок в monobank → покупець оплачує → monobank повідомляє сайт про оплату → створюється фіскальний чек продажу з тими самими товарами й сумою → покупець отримує чек. При поверненні все повторюється у зворотному напрямку: скасування оплати і чек повернення.
Ключове питання — хто створює чек: monobank через налаштовану в кабінеті зв'язку з ПРРО чи ваш сервер напряму через API Checkbox.
Спосіб 1: зв'язка з ПРРО в кабінеті monobank
За документацією monobank, зв'язка з ПРРО налаштовується у веб-кабінеті web.monobank.ua. Коли вона активна, у запиті на створення рахунку (POST /api/merchant/invoice/create) обов'язково передається інформація про замовлення — поле merchantPaymInfo зі складом покупки.
Фіскальні чеки за рахунком можна отримати методом GET /api/merchant/invoice/fiscal-checks. Для кожного чека API повертає тип (sale — продаж, return — повернення), статус (new, process, done, failed), джерело фіскалізації (checkbox або monopay) і, коли чек готовий, посилання на нього на сайті податкової та PDF-файл.
При скасуванні оплати з активною фіскалізацією monobank вимагає передати позиції для чека повернення. Якщо сума холду фіналізується іншою, ніж була в рахунку, можна передати позиції для фіскалізації фактичної суми.
- Плюс: менше власного коду — чек створюється на боці monobank.
- Мінус: сценарії обмежені тим, що підтримує зв'язка; статус чека треба перевіряти окремим запитом.
Спосіб 2: пряма інтеграція з API Checkbox
Ваш сервер отримує від monobank сповіщення про успішну оплату і сам створює чек через API Checkbox. Послідовність за специфікацією Checkbox така:
- Вхід касира: за логіном і паролем або за PIN-кодом.
- Відкриття зміни з ключем ліцензії конкретної каси (заголовок X-License-Key). Зміна спершу створюється в статусі CREATED і переходить в OPENED після підпису КЕП і доставки в ДПС — зазвичай це кілька секунд, тому статус треба відстежувати.
- Створення чека продажу (POST /api/v1/receipts/sell): товари з кодом, назвою і ціною, оплата карткою. Ціна передається в копійках, а кількість — у тисячних: 1 шт = 1000, 2,25 кг = 2250.
- Чек може бути надісланий покупцю на email; для повернення той самий метод створює чек з позначкою повернення.
- Якщо зв'язок з ДПС пропав, Checkbox підтримує офлайн-режим з подальшою відправкою ланцюжка чеків.
Який спосіб обрати
Порівняння двох підходів:
| Зв'язка в кабінеті monobank | Пряма інтеграція з Checkbox | |
|---|---|---|
| Хто створює чек | monobank | Ваш сервер |
| Обсяг розробки | Менший: правильно сформувати рахунок і обробляти статуси | Більший: зміни, касири, чеки, повернення, повтори |
| Гнучкість | У межах можливостей зв'язки | Будь-які сценарії: часткові повернення, кілька кас, нестандартні товари |
| Контроль статусу чека | Запит фіскальних чеків за рахунком | Повний: відповіді API Checkbox у вашій системі |
| Коли підходить | Типовий інтернет-магазин з простими сценаріями | Складна логіка, кілька джерел оплат, власна облікова система |
Типові складнощі
Що варто передбачити заздалегідь, щоб інтеграція не ламалася на нетипових випадках:
- Порядок вебхуків. monobank прямо попереджає, що вебхук про успіх може прийти раніше за «в обробці»; актуальним вважається той, у якого більше значення modifiedDate. Для статусу expired вебхук не надсилається.
- Перевірка підпису. Вебхуки monobank підписані ECDSA; підпис треба перевіряти відкритим ключем, який віддає API, інакше сайт можна обдурити підробленим запитом.
- Подвійні чеки. Повторний вебхук чи повтор після збою не повинен створювати другий чек на ту саму оплату — кожну оплату треба обробляти рівно один раз.
- Розбіжність сум. monobank приймає суму в копійках, Checkbox — ціну в копійках і кількість у тисячних. Знижки й доставку треба розкласти по позиціях так, щоб сума чека збігалася з оплатою.
- Повернення і часткові повернення. Для чека повернення потрібні ті самі позиції, що й у продажу, — їх треба зберігати разом із замовленням.
- Холд. Для оплати з холдом monobank дає 9 днів на фіналізацію і підтримує її лише в гривні; якщо фінальна сума відрізняється, чек має відповідати фактичній сумі.
- Недоступність сервісів. Запити, що не пройшли, мають ставати в чергу і повторюватися, а збої — журналюватися і надходити вам у повідомленні.
Що підготувати перед зверненням
Для оцінки й запуску знадобиться:
- Доступ до кабінету monobank для бізнесу і токен для API інтернет-еквайрингу.
- Каса в Checkbox: ключ ліцензії і дані касира — для прямої інтеграції.
- Перелік товарів з кодами, а також податкові ставки, які застосовуються.
- Сценарії, які треба підтримати: повна оплата, повернення, часткове повернення, холд, знижки, доставка окремою позицією.
- На чому працює сайт або облікова система, до якої підключаємось.
Скільки коштує інтеграція
Одна інтеграція — від 15 000 грн. Вартість залежить від кількості сценаріїв (наприклад, оплата, повернення, часткова оплата) і стану коду, до якого підключаємось. Інтеграцію можна вбудувати в наявний код після аудиту або зробити окремим сервісом, який працює з вашим сайтом через API.