Bepaid (ru)
Як підключити
Для підключення платіжної системи bePaid вам знадобляться ID Магазину, секретний ключ і публічний ключ. Після їх отримання переходимо до налаштувань у MaviBot.
У MaviBot відкриваємо розділ "Еквайринг", обираємо bePaid. Потрібно ввести отримані дані.
Зверніть увагу, що останнє поле є перемикачем хостингу API залежно від країни користування: Білорусь або Росія.
Як сформувати посилання на оплату
Для генерації посилання на оплату вам необхідно встановити значення змінної payment_sum (наприклад 150 або 100.55 (через крапку!)), одразу після цього з’явиться змінна bepaid_pay_url. Цю змінну можна вивести на екран як посилання або розмістити на кнопці з текстом "Оплатити".
Посилання має вигляд: https://checkout.bepaid.by/widget/hpp.html?token=a05eabd3f9368725efbc175614c7d469da08f198cc51916b07fb75e53f9a3e1a
Також до встановлення значення змінної payment_sum можна задати такі необов’язкові змінні для налаштування платежу.
За замовчуванням встановлено білоруський рубль, якщо потрібна інша валюта, потрібно встановити значення змінної currency
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)
link_expired так само можна вказати дату з точним часом, через пробіл, у форматі дд.мм.рррр гг:хх (наприклад: 25.06.2025 12:23). За замовчуванням оплата має бути здійснена протягом 24 годин
Також можна використовувати стандартні змінні, наприклад задамо час дії посилання 30 хвилин:
time = current_time + 30
link_expired = "#{current_date} #{time}"
russian_host
індикатор реєстрації магазину на російському хості bePaid. Вкажіть цей параметр зі значенням 1, якщо ваш магазин зареєстровано на сайті bepaid.tech
Якщо необхідно перемкнути хост на білоруський, вкажіть параметр зі значенням ''
test_payments
змінна потрібна для тестових платежів, якщо потрібен тестовий платіж, додайте її з будь-яким значенням.
bepaid_attempts
вказує кількість спроб здійснити платіж, за замовчуванням дається 1 спроба.
сustomer_data
масив, що містить first_name, last_name і email платника. Дані необхідні для надсилання чека на пошту платника і доступні для редагування на сторінці оплати.
Параметр має бути переданий у вигляді списку у форматі json, що складається з пар ключ-значення
наприклад:
customer_data = ‘{“first_name”: “Vladimir”, “last_name”: “Popov”, “email”: “[email protected]” }’
bepaid_contract (умовно обов’язковий)
призначення платежу за токеном.
Очікувані значення: “recurring” (для регулярних оплат із заданою періодичністю) або “card_on_file” (для нерегулярних платежів, наприклад, післяплата за надану послугу)
Після завершення оплати клієнту буде додано змінну bepaid_callback_data, що містить дані відповіді платіжної системи щодо здійсненої операції. З отриманого словника можна витягти необхідні дані за допомогою методу get.
Як тестувати платежі
Для проведення тестового платежу до вказання змінної payment_sum потрібно задати змінну test_payments з будь-яким значенням.
Не забудьте прибрати її під час запуску бота в бойовому режимі!
Карти для тестів:
4200000000000000 успіх
4005550000000019 невдача
Якщо щось не працює, порівняйте дані з даними на офіційному сайті: https://docs.bepaid.by/ru/test-integration#test-card-number
Приклад формування посилання на оплату
Створимо посилання на оплату в розмірі 100 білоруських рублів (валюта за замовчуванням)
Зверніть увагу, спочатку задаємо додаткові змінні для налаштувань, потім payment_sum. Змінні можна задати й раніше в ланцюжку, а не в одному блоці, це приклад.
Далі в потрібному місці виводимо змінну bepaid_pay_url, у якій міститься посилання
Керування підписками
Інтеграція платіжної системи надає можливість створювати підписки для ваших клієнтів.
Перед початком використання функціоналу MaviBot створіть план підписки в особистому кабінеті bePaid.
Якщо в особистому кабінеті не відображається меню “Плани” і “Підписки”, зверніться до вашого менеджера.
Створення підписки та отримання посилання на оплату
Скористайтеся функцією get_bepaid_subscription_url, передавши їй параметр plan_id, де
plan_id
id плану в системі bePaid.
У результаті виконання функція створить підписку і поверне посилання на її оплату.
Надішліть посилання клієнту та дочекайтеся завершення оплати.
При успішній оплаті підписка активується, у угоду додадуться змінні 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
Опис параметрів:
amount (обов’язковий)
сума платежу, очікуване значення - ціле або десяткове число, наприклад 100 або 100.5;
currency (обов’язковий)
валюта оплати у ISO-4217 форматі, наприклад “USD”
description (обов’язковий)
опис причини списання, наприклад, “Оплата щотижневої підписки на участь у клубі за інтересами”;
contract (обов’язковий)
призначення платежу за токеном. Очікувані значення: “recurring” або “card_on_file”.
Значення contract обов’язково має відповідати значенню, вказаному під час створення посилання на установочний платіж!
Якщо платіж пройшов успішно, функція поверне повідомлення “Успішне списання за токеном bePaid“, ви отримаєте коллбек про успішну оплату, а змінна угоди bepaid_token_payment_completed набуде значення “True”.
Якщо платіж не пройшов, функція поверне повідомлення із зазначенням причини невдалої оплати, в бот надійде коллбек із суфіксом “_fail”, а змінна угоди bepaid_token_payment_completed набуде значення “False”.
Банк може запросити завершення платежу клієнтом. У такому разі функція поверне посилання із запитом проходження аутентифікації 3-D Secure.
Як обробити результат
У відповідь на дії клієнта в бот приходитимуть коллбеки, що складаються з 20 перших символів секретного ключа та суфікса, який залежить від типу та результату операції.
У системі коллбек виглядає як повідомлення від користувача, однак сам користувач його не бачить.
Для оплат
У результаті оплати, що не стосується підписки, вам надійде одне з повідомлень:
номерКлюча_success - при успішній оплаті;
номерКлюча_fail - при невдалій оплаті;
Статус останньої оплати також можна відстежити за змінними bepaid_payment_completed (для оплат за участю клієнта) і bepaid_token_payment_completed (для безакцептних оплат за токеном картки)
Для підписок
Після успішної активації підписки під час першої або повторної оплати в бот надійде повідомлення номерКлюча_success.
Якщо підписку було скасовано, ви отримаєте номерКлюча_canceled.
У разі невдалої оплати за підпискою вам надійде повідомлення номерКлюча_fail.
Last updated