Підключення кнопки monopay

Кнопка monopay — це платіжна кнопка monobank, яку мерчанти можуть вбудувати у свій веб-сайт. Після інтеграції покупці отримують додатковий спосіб оплати через monobank.

Кнопка monopay ще знаходиться у процесі бета тестування, але ви можете підготувати свій веб-сайт до його інтеграції

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: "rounded",
},

			

Детальніше про зовнішний вигляд кнопки у Гайдлайні