Monobank API для чекауту GoHighLevel: огляд підключення та автоматизацій

Принцип роботи інтернет-еквайрингу Monobank API

Monobank Acquiring API надає бізнесу сучасний REST API для прийому платежів картками та через гаманці Apple Pay / Google Pay. Базовий процес обробки складається з кількох етапів:

1. Авторизація через X-Token: Запити до API мерчанта авторизуються за допомогою спеціального токена, отриманого в особистому кабінеті банку.
2. Створення рахунку (Invoice): POST-запит до ендпоінту /api/merchant/invoice/create передає суму платежу в копійках, код валюти (980 для UAH), опис замовлення та URL-адреси для редиректу та вебхука.
3. Оплата покупцем: Банк повертає pageUrl, куди перенаправляється клієнт для завершення платежу.
4. Зворотний вебхук: Після зміни статусу інвойсу Monobank надсилає сповіщення на вказаний webhook URL.

Технічні підводні камені самостійної розробки під GoHighLevel

Багато digital-агенцій та розробників спочатку планують написати пряму інтеграцію через кастомний вебхук або скрипт у Make / Zapier. Проте на практиці виникає низка критичних інженерних складнощів:

1. Криптографічна перевірка підпису x-sign

Для захисту від підробних сповіщень Monobank додає до заголовків вебхука цифровий підпис x-sign (ECDSA SHA-256 base64). Щоб перевірити його, бекенд повинен:

• Зберегти сире тіло запиту (raw buffer) до будь-якого парсингу JSON.
• Отримати публічний ключ банку через /api/merchant/pubkey (з обов'язковим кешуванням у пам'яті чи Redis, щоб не перевищувати rate limits банку).
• Виконати криптографічну верифікацію пари «сирий буфер — сигнатура — публічний ключ».

Хоча низькокодові платформи дозволяють викликати базові функції, самостійна реалізація повного циклу — збереження сирого буфера запиту, динамічне кешування публічного ключа банку, валідація ECDSA-підпису, транзакційна дедуплікація та синхронізація з GHL Custom Payment Provider — вимагає розробки кастомних хмарних воркерів та постійної підтримки інфраструктури.

2. Ідемпотентність та обробка ретраїв

Якщо webhook не доставлено успішно або не отримано статус HTTP 200, Monobank може повторити доставку повідомлення. Тому backend обов'язково повинен бути ідемпотентним і дедуплікувати події за ідентифікатором замовлення та транзакції, щоб уникнути повторного створення контактних нотаток чи дублювання накладних.

3. Робота з GoHighLevel Custom Payment Provider API

Щоб платіжний метод нативно відображався у 1-step або 2-step формах GHL і передавав статус Paid у CRM, необхідно бути зареєстрованим партнером у GoHighLevel Marketplace та підтримувати протокол OAuth 2.0, управління токенами сабакаунтів і динамічну генерацію чекауту.

Порівняння: Власна розробка vs Готовий додаток UkrBilling

Як UkrBilling прибирає технічну рутину

UkrBilling не замінює Monobank API і не є сторонньою платіжною системою. UkrBilling виступає надійним містом між офіційним API банку та внутрішньою архітектурою GoHighLevel:

• Приймає платіжні інвойси від вашого власного мерчанта Monobank.
• Безпечно валідує всі вебхуки на рівні Fastify-бекенду з кешуванням публічних ключів.
• Миттєво оновлює стан замовлення в CRM GoHighLevel через офіційний OAuth 2.0.
• Присвоює тег payment_received та формує структуровану нотатку з Order ID та Invoice ID.
• Передає контекст у чергу генерації накладних Нової Пошти.

Детальніше про налаштування дивіться на сторінці інтеграції: GoHighLevel + Monobank: прийом платежів та автоматизація CRM.

Корисні матеріали: Інтеграція Monobank | Автоматизація Оплата → ТТН | GoHighLevel в Україні