Підключення MonoPay Button
MonoPay Button — це платіжна кнопка monobank, яку мерчанти можуть вбудувати у свій веб-сайт. Після інтеграції покупці отримують додатковий спосіб оплати через monobank.
MonoPay Button ще знаходиться у процесі бета тестування, але ви можете підготувати свій веб-сайт до його інтеграції
1. Підключення скрипта #
1.1. Статичне підключення
HTML
<script src="https://pay.monobank.ua/mono-pay-button/v1/mono-pay-button.js" />
1.2. Динамічне підключення через JavaScript
JavaScript
async function connectMonoPayScript () {
// Перевіряємо чи скрипт вже підключений
const isScriptExists = document.querySelector("#monopay-script");
if (isScriptExists) {
console.log("MonoPay script already loaded");
return;
}
try {
const script = document.createElement("script");
script.id = "monopay-script";
script.src = "https://pay.monobank.ua/mono-pay-button/v1/mono-pay-button.js";
script.onload = initializeMonoPay;
script.onerror = handleScriptError;
document.head.appendChild(script);
} catch (error) {
console.error("Failed to load MonoPay script:", error);
}
}
function handleScriptError () {
console.error("MonoPay script failed to load");
}
2. Ініціалізація віджета #
Після підключення скрипта ви отримуєте доступ до глобального об'єкта window.MonoPay. Метод init() повертає об'єкт з DOM елементом кнопки:
JavaScript
function initializeMonoPay () {
console.log("MonoPay script loaded successfully");
const { button } = window.MonoPay.init({
keyId: "pk_test_your_key_id_here",
signature: "generated_signature_hash",
requestId: "unique_request_id_12345",
payloadBase64: "eyJhbW91bnQiOjUwMDAsImNjeSI6OTgwLCJtZXJjaGFudFBheW1JbmZvIjp7InJlZmVyZW5jZSI6Ijg0ZDAwNzBlZTRlNDQ2NjdiMzEzNzFkOGY4ODEzOTQ3IiwiZGVzdGluYXRpb24iOiLQn9C+0LrRg9C/0LrQsCDRidCw0YHRgtGPIiwiY29tbWVudCI6ItCf0L7QutGD0L/QutCwINGJ0LDRgdGC0Y8ifX0=",
// Налаштування UI
ui: {
buttonType: "pay",
theme: "dark",
corners: "rounded",
},
// Колбеки подій
callbacks: {
onButtonReady: () => {
console.log("MonoPay button is ready");
},
onClick: () => {
console.log("Payment button clicked");
},
onInvoiceCreate: (data) => {
console.log("Invoice created:", data);
// Можна додати додаткову логіку після створення інвойса
},
onSuccess: (result) => {
console.log("Payment successful:", result);
// Перенаправлення або показ повідомлення успіху
},
onError: (error) => {
console.error("Payment error:", error);
// Показ повідомлення про помилку
},
},
});
// Додаємо кнопку на сторінку
const buttonContainer = document.getElementById("payment-container");
if (buttonContainer) {
buttonContainer.appendChild(button);
}
}
3. Конфігурація #
3.1. Параметри конфігурації
CONFIG: object
keyId
required
string
Ідентифікатор ключа криптування, отриманий з API отримання списку ключів для підпису
signature
required
string
Зашифрований підпис даних замовлення, згенерований на бекенді мерчанта за допомогою clientKey. Приклади формування
requestId
required
string
Унікальний ідентифікатор запиту з TTL 10 хвилин. Використовується для забезпечення ідемпотентності операцій
payloadBase64
required
string
Base64 закодовані дані замовлення у форматі JSON. Структура ідентична параметрам API створення рахунку.
ui
object (UIConfig)
Налаштування зовнішнього вигляду кнопки
ui {callbacks
object (CallbackConfig)
Колбек-функції для обробки подій віджета
callbacks {
3.2. Формування payloadBase64 #
payloadBase64 — це base64 закодований JSON об'єкт з даними замовлення. Процес формування відбувається у три етапи:
Приклад формування payloadBase64
// 1. Створюємо об'єкт замовлення
const orderData = {
amount: 5000,
ccy: 980,
merchantPaymInfo: {
reference: "order_123456",
destination: "Покупка товарів",
comment: "Оплата замовлення"
}
};
// 2. Серіалізуємо в JSON строку
const jsonString = JSON.stringify(orderData);
// Результат: '{"amount":5000,"ccy":980,"merchantPaymInfo":{"reference":"order_123456",...}}'
// 3. Кодуємо в base64
const payloadBase64 = btoa(jsonString);
// Результат: "eyJhbW91bnQiOjUwMDAsImNjeSI6OTgwLCJtZXJjaGFudFBheW1JbmZvIjp7InJlZmVyZW5jZSI6Im9yZGVyXzEyMzQ1NiIsImRlc3RpbmF0aW9uIjoi0J/QvtC60YPQv9C60LAg0YLQvtCy0LDRgNGW0LIiLCJjb21tZW50Ijoi0J7Qv9C70LDRgtCwINC30LDQvNC+0LLQu9C10L3QvdGPIn19"
3.3. Структура даних замовлення #
Нижче наведено структуру об'єкта, який має бути закодований у payloadBase64:
ORDER DATA STRUCTURE: object
amount
required
integer <int64>
Сума оплати у мінімальних одиницях (копійки для гривні)
ccy
integer <int32>
ISO 4217 код валюти, за замовчуванням 980 (гривня)
merchantPaymInfo
object
Інформаційні дані замовлення, яке буде оплачуватись. Обовʼязково вказувати при активній звʼязці з ПРРО (звʼязка створюється у веб-кабінеті https://web.monobank.ua)
merchantPaymInfo {redirectUrl
string
URL для повернення після завершення оплати
successUrl
string
URL при успішній оплаті (опціонально)
failUrl
string
URL при неуспішній оплаті (опціонально)
webHookUrl
string
URL для webhook повідомлень про зміну статусу платежу
validity
integer <int64>
Час дії інвойса в секундах (опціонально). За замовчуванням 24 години, максимум 30 днів
agentFeePercent
number <float>
Відсоток комісії, який агент встановлює для себе
Приклад JSON структури
{
"amount": 5000,
"ccy": 980,
"merchantPaymInfo": {
"reference": "84d0070ee4e44667b31371d8f8813947",
"destination": "Покупка щастя",
"comment": "Покупка щастя",
"basketOrder": [
{
"name": "Товар від продавця 1",
"qty": 1,
"sum": 3000,
"code": "product_1",
"splitReceiverId": "sr_aB3dC5eF7g"
},
{
"name": "Товар від продавця 2",
"qty": 1,
"sum": 2000,
"code": "product_2",
"splitReceiverId": "sr_xY9zW8vU6t"
}
]
},
"redirectUrl": "https://example.com/result",
"successUrl": "https://example.com/success",
"failUrl": "https://example.com/fail",
"webHookUrl": "https://example.com/webhook",
"validity": 3600
}
3.4. Формування підпису (signature) #
signature — це цифровий підпис, який формується з:
- JSON.stringify(orderData) — серіалізований об'єкт замовлення
- + requestId — конкатенація з унікальним ідентифікатором
Функція makeSignature() має бути реалізована на вашому бекенді з використанням приватного ключа ECDSA P-256.
Схема формування підпису
// Що підписується:
const orderData = {
amount: 5000,
ccy: 980
// ... інші поля
};
const requestId = "unique_request_id_12345";
// Формуємо строку для підпису
const dataToSign = JSON.stringify(orderData) + requestId;
// Результат: '{"amount":5000,"ccy":980}unique_request_id_12345'
// Підписуємо через власну функцію (реалізується на бекенді)
const signature = makeSignature(dataToSign, privateKey);
// Результат: base64 encoded DER signature
// makeSignature() має реалізувати:
// 1. SHA-256 хешування dataToSign
// 2. ECDSA P-256 підпис хешу
// 3. Кодування в base64
Детальніше про створення інвойсу та приклади формування підпису
4. Методи API #
4.1. Результат ініціалізації
Метод init() повертає об'єкт з DOM елементом кнопки, який можна вставити в будь-яке місце на сторінці:
Вставка кнопки
// Ініціалізуємо віджет
const monoPay = window.MonoPay.init({
keyId: "your_key_id",
signature: "your_signature",
requestId: "unique_id",
payloadBase64: "encoded_order_data"
});
// monoPay.button - готовий DOM елемент кнопки
const container = document.getElementById("payment-container");
container.appendChild(monoPay.button);
// Альтернативно:
document.querySelector("#payment-section").insertAdjacentElement("beforeend", monoPay.button);
4.2. Оновлення конфігурації
Метод update може приймати ті самі налаштування що і метод init
update() метод
window.MonoPay.update({
ui: { theme: "light" },
callbacks: { onSuccess: newSuccessHandler }
});
4.3. Знищення віджета
Метод destroy не потребує передачі параметрів
destroy() метод
window.MonoPay.destroy();
5. Зовнішний вигляд кнопки #
Спробуйте кнопку
Підберіть потрібний варіант кнопки mono Pay, як він виглядатиме
Тип
Форма
Колір
UI налаштування
ui: {
buttonType: "base",
theme: "dark",
corners: "none",
},
5.1 Вільний простір
Розміщуючи кнопку monoPay на сторінці оплати, залишайте навколо неї достатньо «повітря», щоб кнопка залишалась помітною, читабельною та не конфліктувала з іншим контентом.

Завжди залишайте мінімум 8 dp вільного простору з усіх боків кнопки. У цій зоні не має бути тексту, іконок, ліній, рамок, фонів інших блоків або будь-яких декоративних елементів.
5.2 Розміщення
Розміщуйте кнопку monoPay так, щоб її було легко помітити на платіжній сторінці — без пошуків і без прокрутки.

Розміщуйте кнопку у видимій зоні платіжного екрану. Кнопка monoPay має бути не меншою, ніж інші основні кнопки оплати. Не змушуйте користувача скролити, щоб знайти кнопку.
Завжди на темних фонах використовуйте білий варіант кнопки — для достатнього контрасту та читабельності.

5.2 Під кожен тип оплати
Використовуйте той варіант кнопки monoPay, який відповідає дії користувача.
base
Для вебсайту або застосунку, коли monoPay показується як спосіб оплати без заклику до дії — наприклад, у списку платіжних методів або коли поруч уже є основна CTA-кнопка.
pay
Для вебсайту або застосунку, де користувач оплачує товар або послугу. Використовуйте, коли натискання кнопки означає оплату тут і зараз.
subscribe
Для вебсайту або застосунку, де користувач оформлює підписку. Використовуйте лише для регулярних платежів, які повторюються автоматично у визначений період.