Інтеграція Checkbox з monobank: оплата на сайті і фіскальний чек

Покупець оплачує замовлення на сайті через інтернет-еквайринг monobank, а фіскальний чек має з'явитися в ПРРО Checkbox — без ручного введення. Є два способи це налаштувати. Розбираємо обидва, а також повернення, вебхуки і місця, де інтеграції найчастіше ламаються.

Оновлено:

Що саме треба зв'язати

Ланцюжок виглядає так: сайт створює рахунок в 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.

Часті питання

Чи можна видавати чеки Checkbox автоматично після оплати через monobank?

Так. Або через зв'язку з ПРРО в кабінеті monobank — тоді в рахунку передається склад замовлення, — або через пряму інтеграцію: ваш сервер після підтвердження оплати створює чек через API Checkbox.

Що буде, якщо Checkbox або monobank тимчасово не відповідає?

Запити ставляться в чергу і повторюються, а збої журналюються і надходять вам у повідомленні. Checkbox також має офлайн-режим для випадків, коли немає зв'язку з ДПС.

Чи підійде це для сайту не на Laravel?

Так. Інтеграцію можна зробити окремим сервісом, який працює з вашим сайтом через API, або вбудувати в наявний код після аудиту.

Пов'язана послуга

Інтеграції та автоматизація

Беремо задачу під ключ: розбираємо ваші процеси, робимо і запускаємо рішення, а потім підтримуємо його.

Вартість
від 15 000 грн

Розкажіть про вашу задачу

Перша консультація безкоштовна. Відповідь протягом 24 годин.

Орієнтовний бюджет (необов'язково)

Не хочете заповнювати форму? Написати в Telegram

Розкажіть про вашу задачу

Перша консультація безкоштовна. Відповідь протягом 24 годин.

Орієнтовний бюджет (необов'язково)

Не хочете заповнювати форму? Написати в Telegram