Як підключити еквайринг Monobank без програміста через вайбкодинг

Вайбкодинг докорінно змінив розробку цифрових продуктів. Сьогодні, щоб додати на сайт прийом платежів через Apple Pay, Google Pay або банківські картки, більше не потрібно наймати бекенд-розробника чи самостійно розбиратися в криптографічних протоколах. Достатньо вміти чітко сформулювати бізнес-логіку своєму AI-агенту (Codex, Antigravity, Cursor або Claude Code) та надати йому правильний контекст технічної документації.

У цьому посібнику розібрано повний життєвий цикл підключення інтернет-еквайрингу Monobank до вашого проєкту: від проходження комплаєнсу банку та налаштування кабінету підприємця до генерації захищеного платіжного шлюзу з криптографічною верифікацією підписів ECDSA у вебхуках, обробки стану гонки в інтерфейсі та набору обов'язкових автотестів.

1. Архітектура Hosted Checkout та життєвий цикл платежу

Monobank Acquiring працює за схемою Hosted Checkout (оплата на захищеній сторінці банку). Це означає, що вашому сайту не потрібна складна та дорога сертифікація безпеки PCI DSS, оскільки платіжні дані карток користувач вводить безпосередньо на захищеному домені банку.

Офіційна документація Monobank для AI-інструментів доступна за адресою monobank.ua/api-docs/acquiring/dev/ai-tools/docs--ai-prompts →. Збережіть це посилання як канонічне першоджерело технічних вимог банку.

1.1. Базовий платіжний флоу

• 1. Створення рахунку (invoice/create): Клієнт на вашому сайті обирає товар чи тариф. Серверний обробник надсилає POST-запит до Monobank API з сумою, призначенням платежу та адресою для повернення. Банк повертає унікальний invoiceId та посилання pageUrl.
• 2. Редирект на платіжну сторінку: Клієнт перенаправляється на pageUrl, де оплачує замовлення через Apple Pay, Google Pay, застосунок Monobank або введення даних банківської картки.
• 3. Отримання Webhook: Після завершення оплати Monobank автоматично надсилає POST-запит на ваш заздалегідь налаштований webHookUrl зі статусом транзакції та криптографічним цифровим підписом.
• 4. Фіксація статусу (Terminal States): Ваш сервер зобов'язаний реагувати на два фінальні статуси: success (платіж успішний, відкриваємо доступ або відправляємо замовлення) та failure (помилка або відхилення платежу банком).

2. Юридичні передумови та чекліст комплаєнсу сайту для ФОП

Навіть якщо платіжний код написаний бездоганно, служба фінансового моніторингу та безпеки Monobank не активує бойовий прийом платежів, якщо сайт не відповідає вимогам законодавства України та правилам платіжних систем Visa/Mastercard.

2.1. Банківські передумови

• Відкритий рахунок ФОП або юрособи в Monobank: Еквайринг підключається виключно до підприємницьких рахунків. На особисту чорну чи білу картку фізособи приймати комерційні платежі за законом заборонено.
• Відповідні КВЕДи: У реєстраційних даних ФОП мають бути зазначені коди діяльності для інтернет-торгівлі чи послуг (наприклад, 47.91 — Роздрібна торгівля через інтернет, 62.01/62.02 — Комп'ютерне програмування та консультації, 85.59 — Інші види освіти).

2.2. Обов'язковий чекліст сторінок перед подачею на модерацію

Перед тим як подати заявку на активацію інтернет-термінала, переконайтеся, що на вашому сайті є наступні розділи (зазвичай розміщуються в футері):

• Публічна оферта (Договір публічної оферти): Опис предмета угоди, моменту укладання договору, прав та обов'язків сторін.
• Політика конфіденційності (Privacy Policy): Чітке формулювання того, які дані клієнтів збираються і як вони захищаються відповідно до ЗУ «Про захист персональних даних».
• Умови повернення коштів та доставки: Порядок повернення товару або коштів протягом 14 днів за Законом України «Про захист прав споживачів», а для цифрових товарів/підписок — правила відмови від послуги.
• Повні реквізити підприємця в футері сайту: Найменування ФОП або ТОВ, ІПН / ЄДРПОУ, юридична адреса, контактний номер телефону та робочий e-mail служби підтримки.
• Прозорі ціни та опис: Кожна кнопка оплати повинна мати фіксовану суму в гривнях (UAH) та зрозумілий опис того, за що саме платить клієнт.

3. Створення веб-термінала в кабінеті Monobank Бізнес

Для взаємодії з платіжним API вам потрібен персональний ключ доступу — X-Token. Він генерується безкоштовно всередині особистого кабінету підприємця.

3.1. Покроковий алгоритм відкриття каси

1. Авторизація: Перейдіть на web.monobank.ua → та увійдіть за допомогою QR-коду через додаток Monobank на смартфоні.
2. Перехід до каси: У лівому навігаційному меню виберіть розділ «Каса».
3. Додавання інструменту: Натисніть кнопку «+ Додати інструмент» та оберіть варіант «Оплати на сайті (власна розробка)».
4. Реєстрація термінала: Введіть назву проєкту (наприклад, Мій сайт або Основний термінал) та підтвердіть операцію кнопкою «Підключити».
5. Генерація API-токена: Відкрийте створений термінал, перейдіть у вкладку «Інтеграції / API Ключі», натисніть «Створити токен» і скопіюйте згенерований ключ.

📍 Навігація в кабінеті: web.monobank.ua → Каса → + Додати інструмент → Оплати на сайті (власна розробка)

Створення платіжного інструмента в кабінеті Monobank Kasa ЗбільшитиСтворення платіжного інструмента в кабінеті Monobank Kasa

📍 Отримання API-ключа: Каса → Ваш термінал → Інтеграція → Створити X-Token

Модальне вікно створення та копіювання токена доступу X-Token ЗбільшитиМодальне вікно створення та копіювання токена доступу X-Token

3.2. Залізні правила безпеки токенів

• Жодного хардкоду в клієнтському коді: X-Token дає прямий доступ до керування вашими фінансами та поверненнями. Його категорично заборонено зберігати у відкритому JavaScript/HTML або публікувати у відкритих репозиторіях GitHub.
• Використання змінних оточення: Зберігайте токен виключно у файлі .env на сервері під назвою MONOBANK_TOKEN або в розділі Secrets вашої хостинг-платформи (Vercel, Render, Railway, Replit, Lovable).
• Тестовий токен для розробки: Для початкових експериментів банк надає окремий тестовий токен на сторінці api.monobank.ua →, який дозволяє симулювати транзакції без списання реальних коштів.

4. Офіційні AI-промпти Monobank для вайб-кодерів

Команда Monobank розробила набір офіційних системних промптів для AI-агентів. Їхня головна перевага — точна відповідність актуальним ендпоінтам банку.

Сторінка офіційної документації Monobank для AI-інструментів ЗбільшитиСторінка офіційної документації Monobank для AI-інструментів

4.1. Базовий промпт створення платежу

Скопіюйте цей промпт і надішліть його у чат вашого AI-асистента:

4.2. Промпт для налаштування Webhook-обробника

Без вебхука сервер не дізнається про факт успішної оплати, якщо клієнт закриє браузер одразу після списання:

5. Пакет скілів monobank-acquiring: прокачування агента

Якщо обмежитися лише коротким промптом, AI-асистент напише базовий код (приблизно 6.8 із 10): кнопка спрацює, але код не міститиме перевірки криптографічних підписів, захисту від підміни ціни та обробки рідкісних помилок мережі.

Щоб отримати продакшен-рівень (9.8–10 балів), у корінь проєкту додається спеціалізований пакет скілів monobank-acquiring.

Аудит платіжної інтеграції: порівняння безпеки до та після використання скіла ЗбільшитиАудит платіжної інтеграції: порівняння безпеки до та після використання скіла

5.1. Анатомія та структура пакета скілів

6. Практична реалізація: динамічний платіжний флоу

У кожному проєкті своя структура: хтось продає цифрові консультації з фіксованими тарифами, хтось має інтернет-магазин із динамічним кошиком, а хтось — простий лендінг з однією кнопкою донату чи передплати.

Головна помилка початківців — жорстко «зашивати» суму (наприклад, 1000 грн) прямо в клієнтський код кнопки або в тіло POST-запиту з браузера. Цей підхід створює критичну вразливість безпеки.

6.1. Принцип безпеки: динамічна ціна замість хардкоду

• Ніколи не довіряйте сумі з браузера: Якщо клієнтський JavaScript надсилає на сервер { price: 1000 }, зловмисник через інспектор коду (DevTools) або Postman може підмінити це значення на { price: 1 } і придбати доступ за 1 гривню.

• Сервер — єдине джерело правди (Single Source of Truth): Фронтенд передає на бекенд лише ідентифікатор товару (productId), обраний тариф (planId: "pro") або масив ідентифікаторів кошика (items: [{ id: "book_1", qty: 2 }]).

• Автоматична конвертація в копійки: Сервер дістає актуальну вартість із конфігураційного файлу або бази даних і самостійно множить її на 100:

  $$\text{amount} = \text{Math.round}(\text{realPrice} \times 100)$$ Якщо ви зміните ціну в базі або оголосите знижку, рахунок Monobank згенерується з новою правильною сумою без втручання в платіжний шлюз.

6.2. Універсальний AI-промпт для адаптації під будь-який проєкт

Скопіюйте цей промпт і надішліть його у чат вашого AI-агента (Codex, Antigravity, Cursor або Claude Code). Агент сам просканує файли вашого сайту, знайде існуючі кнопки й ціни та побудує надійну інтеграцію:

Робота AI-агента в IDE з аналізом структури та створенням динамічного ендпоінта ЗбільшитиРобота AI-агента в IDE з аналізом структури та створенням динамічного ендпоінта

6.3. Архітектурний шаблон бекенду створення інвойсу

Ось перевірені серверні реалізації для двох найпопулярніших веб-стеків:

typescript
Копіювати
// app/api/checkout/create-invoice/route.ts
import { NextResponse } from "next/server";

const PRODUCTS_CATALOG: Record<string, { title: string; priceUah: number }> = {
  plan_starter: { title: "Тариф Starter", priceUah: 490 },
  plan_pro:     { title: "Тариф Pro",     priceUah: 990 },
  plan_vip:     { title: "Тариф VIP",     priceUah: 2490 },
};

export async function POST(req: Request) {
  try {
    const { productId } = await req.json();

    // 1. Валідація: ціна формується виключно на бекенді
    const product = PRODUCTS_CATALOG[productId];
    if (!product) {
      return NextResponse.json({ error: "Обраний товар або тариф не знайдено" }, { status: 400 });
    }

    const amountInKopecks = Math.round(product.priceUah * 100);
    const orderReference = `order_${productId}_${Date.now()}`;
    const siteUrl = process.env.NEXT_PUBLIC_SITE_URL || "https://mysite.com";

    // 2. Запит до Monobank API
    const response = await fetch("https://api.monobank.ua/api/merchant/invoice/create", {
      method: "POST",
      headers: {
        "X-Token": process.env.MONOBANK_TOKEN!,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        amount: amountInKopecks,
        ccy: 980, // Гривня (ISO 4217)
        merchantPaymInfo: {
          reference: orderReference,
          destination: `Оплата: ${product.title}`,
          comment: `Замовлення ${orderReference}`,
        },
        redirectUrl: `${siteUrl}/payment-result?ref=${orderReference}`,
        webHookUrl: `${siteUrl}/api/payment/webhook`,
        validity: 3600, // Рахунок діє 1 годину
      }),
    });

    const data = await response.json();
    if (!response.ok) {
      return NextResponse.json({ error: data.errText || "Помилка створення рахунку в банку" }, { status: response.status });
    }

    return NextResponse.json({ checkoutUrl: data.pageUrl, invoiceId: data.invoiceId });
  } catch (error) {
    return NextResponse.json({ error: "Внутрішня помилка ініціалізації платежу" }, { status: 500 });
  }
}

7. Безпечна обробка вебхуків та криптографічний підпис ECDSA

Найвідповідальніша частина будь-якої фінансової інтеграції — верифікація сповіщень про оплату. Зловмисник може надіслати підроблений HTTP-запит на вашу адресу /api/payment/webhook з фальшивим повідомленням про успіх.

Щоб запобігти цьому, Monobank підписує кожен вебхук за допомогою асиметричного алгоритму ECDSA (крива secp256r1 / SHA-256) та передає сигнатуру в HTTP-заголовку x-sign.

7.1. Чому JSON.stringify ламає верифікацію підпису

7.2. Реалізація верифікації вебхука

Нижче наведено правильну реалізацію отримання сирого тіла та верифікації для Next.js App Router та Express:

typescript
Копіювати
// app/api/payment/webhook/route.ts
import { NextResponse } from "next/server";
import crypto from "crypto";

let cachedPubKey: string | null = null;

async function getMonobankPubKey(token: string): Promise<string> {
  if (cachedPubKey) return cachedPubKey;

  const res = await fetch("https://api.monobank.ua/api/merchant/pubkey", {
    headers: { "X-Token": token },
    next: { revalidate: 86400 }, // Кешуємо публічний ключ на 24 години
  });
  const data = await res.json();
  cachedPubKey = `-----BEGIN PUBLIC KEY-----\n${data.key}\n-----END PUBLIC KEY-----`;
  return cachedPubKey;
}

export async function POST(req: Request) {
  const signature = req.headers.get("x-sign");
  if (!signature) {
    return new NextResponse("Missing x-sign header", { status: 400 });
  }

  // 1. Отримуємо сире незмінене тіло запиту у вигляді тексту
  const rawBody = await req.text();

  try {
    const pubKey = await getMonobankPubKey(process.env.MONOBANK_TOKEN!);

    // 2. Верифікуємо підпис ECDSA SHA-256
    const verifier = crypto.createVerify("SHA256");
    verifier.update(rawBody);
    const isValid = verifier.verify(pubKey, Buffer.from(signature, "base64"));

    if (!isValid) {
      console.error("Вебхук відхилено: недійсний підпис x-sign");
      return new NextResponse("Invalid signature", { status: 400 });
    }

    // 3. Парсимо дані тільки після успішної перевірки криптографії
    const payload = JSON.parse(rawBody);
    const { invoiceId, status, amount, reference } = payload;

    if (status === "success") {
      // Тут активуємо замовлення в базі даних з перевіркою на дублікати (ідемпотентність)
      console.log(`Замовлення ${reference} (${invoiceId}) оплачено на суму ${amount / 100} грн`);
    }

    return new NextResponse("OK", { status: 200 });
  } catch (error) {
    console.error("Помилка обробки вебхука:", error);
    return new NextResponse("Internal verification error", { status: 500 });
  }
}

8. Локальне тестування вебхуків (Localhost & Cloudflare Tunnels)

Поширена проблема вайбкодерів: при запуску сервера на http://localhost:3000 банк не може доставити вебхук, оскільки локальна машина не має публічної IP-адреси в інтернеті.

Monobank надсилає вебхуки виключно на публічні адреси з дійсним протоколом HTTPS. Щоб протестувати повний цикл на своєму комп'ютері, прокиньте безпечний тунель.

8.1. Швидкий запуск тунелю (без реєстрації та безкоштовно)

Скористайтеся Cloudflare Tunnel (cloudflared) або untun:

bash
Копіювати
# Миттєвий HTTPS-тунель на 3000 порт без встановлення утиліт
npx untun@latest tunnel --port 3000

Після запуску ви отримаєте тимчасову публічну HTTPS-адресу, наприклад: https://your-tunnel-name.trycloudflare.com

8.2. Налаштування вебхука для локального тесту

У коді створення інвойсу під час розробки вкажіть отриману адресу:

Тепер при тестовій оплаті банк надішле реальний вебхук прямо на ваш локальний сервер у терміналі, і ви зможете переконатися, що підпис x-sign успішно проходить перевірку.

9. UX сторінки повернення та вирішення стану гонки (Race Condition)

Коли клієнт оплачує рахунок через застосунок Monobank або Apple Pay, банк повертає його на адресу redirectUrl (/payment-result?ref=...) миттєво.

Проте мережевий вебхук від сервера банку до вашого сервера може затриматися на 1–2 секунди через мережеві маршрути. Якщо сторінка результату одразу перевірить статус у базі даних, вона ризикує показати: «Замовлення не оплачено», що спричинить паніку у клієнта (кошти з картки списано, а сайт повідомляє про відсутність оплати).

9.1. Інженерний патерн вирішення гонки

1. Початковий стан завантаження: Сторінка відкривається з нейтральним статусом: «Підтверджуємо оплату в банку...» та анімованим індикатором.
2. Короткий поллінг (Short Polling): Фронтенд робить до 5 швидких запитів до власного API кожні 1.5 секунди (/api/orders/check-status?ref=...), очікуючи, поки вебхук змінить статус замовлення в базі на success.
3. Фолбек: Якщо за 8 секунд вебхук не дійшов, клієнт бачить повідомлення: «Платіж прийнято в обробку. Щойно банк підтвердить транзакцію, доступ відкриється автоматично».

9.2. Готовий React-компонент сторінки результату

10. Розширені можливості: вбудоване пРРО, холдування та Wallet

Monobank Acquiring надає повний спектр інструментів для складніших бізнес-моделей:

Фінальна сторінка оплати Monobank Hosted Checkout з Apple Pay та картками ЗбільшитиФінальна сторінка оплати Monobank Hosted Checkout з Apple Pay та картками

10.1. Програмне РРО: безкоштовний вбудований Checkbox у Касі Monobank

Для більшості українських ФОПів 2-ї та 3-ї груп обов'язкова фіскалізація онлайн-продажів є юридичною вимогою.

Головна перевага Monobank для підприємців — безкоштовна вбудована інтеграція з сервісом пРРО Checkbox:

• Увімкнення в один клік: У кабінеті web.monobank.ua перейдіть у налаштування створеного термінала та активуйте перемикач «Фіскалізація через Checkbox». Monobank сам безкоштовно створює касу та підписує чеки вашим КЕП.
• Автоматична фіскалізація: Якщо у вас стандартний каталог товарів з однаковою ставкою, вам навіть не потрібно змінювати код створення платежу — чек автоматично формується за полем destination у призначенні платежу.
• Розширена фіскалізація через API: Якщо ви продаєте товари з різними ставками ПДВ або підакцизні позиції з кодами УКТ ЗЕД, передавайте масив basketOrder всередині об'єкта merchantPaymInfo:

10.2. Двоетапна оплата (Hold)

Якщо ви продаєте фізичні товари, які можуть бути відсутні на складі, використовуйте режим холдування:

• Блокування: Передайте paymentType: "hold" під час створення інвойсу. Кошти заморожуються на картці покупця на строк до 9 днів.
• Списання (Finalize): Після перевірки наявності товару викличте /api/merchant/invoice/finalize. Можна списати як повну суму, так і меншу (наприклад, якщо однієї позиції не виявилося).
• Скасування: Якщо товару немає, викличте /api/merchant/invoice/cancel — платіж скасовується без жодних банківських комісій для покупця.

10.3. Збереження карток та підписки (Wallet)

Якщо ви запускаєте SaaS-сервіс із регулярною щомісячною передплатою, передайте saveCardData: true під час створення першого інвойсу. Після успішної оплати у вебхуку повернеться walletId. Використовуйте цей токен для наступних автоматичних списань без повторного введення даних картки клієнтом.

11. Матриця безпеки та автоматичні тести (Vitest / Jest)

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

Перед переходом у бойовий режим запустіть тестову матрицю безпеки:

11.1. Готовий набір автоматичних тестів для вашого проєкту

Попросіть свого AI-агента додати наступний тестовий набір до проєкту (monobank-acquiring.test.ts):

12. Фінальний інженерний чекліст перед запуском

Перевірте свій платіжний модуль за цими 10 пунктами перед перемиканням на бойові платежі:

• Комплаєнс сайту: У футері додано посилання на Публічну оферту, Політику конфіденційності, Умови повернення та повні реквізити ФОП з ІПН.
• Суми в копійках: Усі значення amount помножені на 100 ($1\text{ грн} = 100\text{ коп}$) через Math.round.
• Безпека ключа: Токен винесено в .env під назвою MONOBANK_TOKEN та додано в .gitignore.
• Ціни з бекенду (SSOT): Клієнт передає лише ідентифікатор товару, сума береться виключно з бази чи конфігу.
• Обробка rawBody: Вебхук верифікує оригінальний текстовий або бінарний буфер (req.text() або req.rawBody), уникаючи подвійного парсингу через JSON.stringify.
• Криптографічний захист: Вебхук верифікує підпис x-sign через публічний ключ банку алгоритмом SHA256 ECDSA.
• Публічний URL для вебхука: Сервер доступний ззовні через дійсний SSL-сертифікат HTTPS (для локальних тестів підходить Cloudflare Tunnel або ngrok).
• Ідемпотентність: Повторний прихід одного й того ж вебхука не викликає подвійну видачу товару чи підписки.
• UX сторінки результату: На /payment-result налаштовано лоадер очікування та короткий поллінг статусу, щоб захистити користувача від стану гонки.
• Реальний платіж на 1–5 грн: Проведено успішну тестову транзакцію реальною карткою, перевірено списання коштів та відображення в кабінеті банку.

Корисні ресурси та файли для завантаження

• Завантажити пакет скілів monobank-acquiring.zip (38 KB) →
• Офіційна сторінка AI Промптів Monobank →
• Особистий кабінет Monobank Бізнес →
• Практичне відео на YouTube з повним розбором флоу →
• Портал тестування API Monobank →