Bepaid

04.08.2026

На цій сторінці

Як підключити

Для підключення платіжної системи bePaid вам знадобляться Store ID, секретний ключ та публічний ключ. Отримавши ці облікові дані, перейдіть до налаштувань платіжної системи в MaviBot.

Щоб отримати Store ID, секретний ключ та публічний ключ, зверніться до технічної підтримки bePaid.

У MaviBot відкрийте розділ Еквайринг, виберіть bePaid та введіть отримані облікові дані.

Примітка: Останнє поле — це перемикач, який вибирає кінцеву точку API залежно від країни використання: Білорусь або Росія.

Як створити платіжне посилання

Щоб створити платіжне посилання, призначте значення змінній payment_sum (наприклад: 150 або 100.55; використовуйте крапку як десятковий роздільник).

Після встановлення змінної payment_sum змінна bepaid_pay_url створюється автоматично. Ви можете відобразити цю змінну як посилання в повідомленні або використати її в кнопці з текстом "Оплатити".

Параметр функції	Опис	Додаткова інформація
currency	Валюта платежу у форматі ISO 4217.	Наприклад: USD
language	Мова сторінки оплати. За замовчуванням: `en`.	Дозволені значення: • `en` — англійська • `es` — іспанська • `tr` — турецька • `de` — німецька • `it` — італійська • `ru` — російська • `zh` — китайська • `fr` — французька • `da` — данська • `sv` — шведська • `no` — норвезька • `fi` — фінська • `pl` — польська • `ja` — японська • `uk` — українська • `be` — білоруська • `ka` — грузинська • `ro` — румунська
payment_description	Опис платежу.	—
link_expired	Термін дії платіжного посилання. Встановіть дату закінчення у форматі `дд.мм.рррр` (наприклад: `25.06.2025`). За замовчуванням платіж має бути завершено протягом 24 годин.	Ви також можете використовувати поле Призначити змінні при перенаправленні: • `link_expired = current_date + 2` — посилання буде дійсним протягом 2 днів до 00:00. • Ви можете вказати точну дату та час закінчення у форматі `дд.мм.рррр гг:хв` (наприклад: `25.06.2025 12:23`). Також можна використовувати стандартні змінні. Приклад для посилання, дійсного протягом 30 хвилин: `python\ntime = current_time + 30\nlink_expired = "#{current_date} #{time}"\n`
russian_host	Індикатор для магазину, зареєстрованого на російському хості bePaid. Встановіть цей параметр у `1`, якщо ваш магазин зареєстровано на bepaid.tech.	Щоб переключитися на білоруський хост, встановіть цей параметр у `""` (порожнє значення).
test_payments	Вмикає тестові платежі. Призначте будь-яке значення цій змінній перед створенням платіжного посилання.	—
bepaid_attempts	Вказує кількість спроб оплати. За замовчуванням дозволена 1 спроба.	—
customer_data	JSON-об'єкт, що містить first_name, last_name та email платника. Ця інформація необхідна для надсилання квитанції про оплату та може бути відредагована на сторінці оплати.	Параметр має бути переданий як об'єкт у форматі JSON. Приклад: `python\ncustomer_data = {\n \"first_name\": \"Sam\",\n \"last_name\": \"Smith\",\n \"email\": \"[email protected]\"\n}\n`
bepaid_contract (умовно обов'язковий)	Призначення платежу для платежів за токеном.	Дозволені значення: • `recurring` — для регулярних платежів із фіксованим графіком. • `card_on_file` — для одноразових або нерегулярних платежів, наприклад, списання коштів з клієнта після надання послуги.

Приклад платіжного посилання:

https://checkout.bepaid.by/widget/hpp.html?token=a05eabd3f9368725efbc175614c7d469da08f198cc51916b07fb75e53f9a3e1a

Перед призначенням значення payment_sum ви можете визначити додаткові необов'язкові змінні для налаштування платежу.

За замовчуванням валюта платежу — білоруський рубль (BYN). Якщо ви хочете використовувати іншу валюту, призначте значення змінній currency.

Після завершення платежу до клієнта додається змінна bepaid_callback_data. Вона містить відповідь платіжної системи про виконану транзакцію.

Ви можете отримати необхідні значення з цього словника за допомогою функції get().

Як тестувати платежі

Щоб виконати тестовий платіж, призначте будь-яке значення змінній test_payments до встановлення змінної payment_sum.

Важливо: Видаліть змінну test_payments перед переведенням вашого бота в робочий режим.

Тестові картки

Номер картки	Результат
`4200000000000000`	Успішний платіж
`4005550000000019`	Невдалий платіж

Приклад створення платіжного посилання

У наведеному нижче прикладі створюється платіжне посилання на 100 білоруських рублів (валюта за замовчуванням).

Примітка: Спочатку призначте будь-які додаткові змінні конфігурації, потім призначте значення payment_sum. Ці змінні також можна призначити раніше у вашому робочому процесі — вони не обов'язково мають бути в одному блоці.

Нарешті, відобразіть змінну bepaid_pay_url там, де це необхідно. Вона містить згенероване платіжне посилання.

Керування підписками

Інтеграція bePaid дозволяє створювати підписки для ваших клієнтів.

Перед використанням цієї функціональності в MaviBot створіть план підписки в обліковому записі bePaid.

Якщо розділи Плани та Підписки недоступні у вашому обліковому записі, зверніться до свого менеджера.

Створення підписки та генерація платіжного посилання

Використовуйте функцію get_bepaid_subscription_url та передайте параметр plan_id.

Функція створює підписку та повертає платіжне посилання.

Надішліть згенероване посилання клієнту та зачекайте на завершення оплати.

Після успішної оплати:

підписка активується;
угода отримує змінні:
- bepaid_subscription_id;
- bepaid_subscription_status;
боту надсилається зворотний виклик (див. Як обробити результат).

Отримання інформації про підписку

Щоб отримати поточну інформацію про підписку, використовуйте функцію get_bepaid_subscription_info.

Передайте параметр subscription_id. Його значення можна взяти зі змінної bepaid_subscription_id.

Скасування підписки

Щоб скасувати підписку, використовуйте функцію cancel_bepaid_subscription.

Функція приймає один параметр:

subscription_id — значення можна взяти зі змінної bepaid_subscription_id.

Після успішного скасування:

змінна bepaid_subscription_status встановлюється у "canceled";
боту надсилається зворотний виклик (див. Як обробити результат).

Статуси підписок

Статус	Опис
trial	Активна або скасована підписка пробного періоду.
active	Активна підписка з вчасно здійсненим платежем.
failed	Невдала підписка. bePaid не зміг обробити наступний платіж.
error	Сталася помилка під час спроби bePaid обробити платіж.
canceled	Підписку скасовано і вона більше не активна.

Регулярні платежі

Ви також можете налаштувати регулярні платежі без створення плану підписки в обліковому записі bePaid.

Для цього вам знадобиться токен картки клієнта.

Отримання токена картки

Щоб отримати токен картки клієнта, клієнт повинен виконати початковий платіж за допомогою платіжного посилання, згенерованого зі змінною payment_sum.

Перед призначенням значення payment_sum встановіть змінну bepaid_contract, щоб визначити призначення майбутніх платежів за токеном.

Підтримувані значення:

recurring — для регулярних платежів із попередньо визначеним графіком.
card_on_file — для одноразових або нерегулярних платежів, наприклад, списання коштів з клієнта після надання послуги.

Примітка: Опція card_on_file підтримується не всіма банками-еквайрами. Зверніться до свого менеджера, якщо плануєте використовувати цю опцію.

Після успішної оплати до угоди додається змінна bepaid_client_card_token. Вона зберігає токен картки клієнта, який можна використовувати для майбутніх платежів без взаємодії з клієнтом.

Далі налаштуйте свій робочий процес, визначте необхідну дату або умову для списання коштів з клієнта та викличте функцію make_bepaid_token_payment.

Параметри мають бути передані в наступному порядку:

amount → currency → description → contract

Опис параметрів

Значення параметра contract має точно збігатися зі значенням, вказаним під час генерації початкового платіжного посилання.

Параметр	Опис
amount (обов'язковий)	Сума платежу. Значення має бути цілим або десятковим числом, наприклад: `100` або `100.5`.
currency (обов'язковий)	Валюта платежу у форматі ISO 4217, наприклад: `USD`.
description (обов'язковий)	Опис платежу, наприклад: `"Щотижнева оплата підписки за участь у клубі за інтересами"`.
contract (обов'язковий)	Призначення платежу за токеном. Дозволені значення: `recurring` або `card_on_file`.

Якщо платіж успішний:

функція повертає повідомлення "Successful charge via bePaid token";
бот отримує зворотний виклик про успішний платіж;
змінна bepaid_token_payment_completed встановлюється у True.

Якщо платіж невдалий:

функція повертає повідомлення з описом причини невдачі;
бот отримує зворотний виклик із суфіксом _fail;
змінна bepaid_token_payment_completed встановлюється у False.

Якщо банк вимагає додаткової перевірки клієнта, функція повертає посилання, за яким клієнт може пройти 3-D Secure аутентифікацію.

Як обробити результат

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

Зворотний виклик з'являється в системі як повідомлення користувача, але він не видимий для клієнта.

Зворотні виклики платежів

Для одноразових платежів бот отримує один із наступних зворотних викликів:

keyNumber_success — успішний платіж.
keyNumber_fail — невдалий платіж.

Ви також можете відстежувати результат платежу за допомогою наступних змінних:

bepaid_payment_completed — платіж виконано клієнтом.
bepaid_token_payment_completed — автоматичний платіж виконано за допомогою токена картки клієнта.

Зворотні виклики підписок

Після успішної активації підписки, під час початкового або регулярного платежу, бот отримує:

keyNumber_success

Якщо підписку скасовано, бот отримує:

keyNumber_canceled

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

keyNumber_fail