# Bepaid (ru)

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

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

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

<div data-with-frame="true"><figure><img src="/files/c66429da09acd59ab506b116c6f9bcfbdc57cb73" alt=""><figcaption></figcaption></figure></div>

Зверніть увагу, що останнє поле є перемикачем хостингу API залежно від країни користування: Білорусь або Росія.

<div data-with-frame="true"><figure><img src="/files/df856a037c15a14160024e0ab9ce48866220049e" alt=""><figcaption></figcaption></figure></div>

## Як сформувати посилання на оплату

Для генерації посилання на оплату вам необхідно встановити значення змінної payment\_sum (наприклад 150 або 100.55 (через крапку!)), одразу після цього з’явиться змінна bepaid\_pay\_url. Цю змінну можна вивести на екран як посилання або розмістити на кнопці з текстом "Оплатити".&#x20;

Посилання має вигляд: \
<https://checkout.bepaid.by/widget/hpp.html?token=a05eabd3f9368725efbc175614c7d469da08f198cc51916b07fb75e53f9a3e1a>

Також до встановлення значення змінної payment\_sum можна задати такі необов’язкові змінні для налаштування платежу.

{% hint style="info" %}
За замовчуванням встановлено білоруський рубль, якщо потрібна інша валюта, потрібно встановити значення змінної currency
{% endhint %}

<table><thead><tr><th width="209">Параметри функції</th><th width="242">Опис параметра</th><th>Додатково</th></tr></thead><tbody><tr><td><strong>currency</strong></td><td>валюта оплати у <a href="http://en.wikipedia.org/wiki/ISO_4217">ISO-4217</a> форматі</td><td>наприклад USD</td></tr><tr><td><strong>language</strong></td><td><p>мова сторінки оплати</p><p>За замовчуванням - en.</p></td><td><p>Допустимі значення:</p><p>en - Англійська</p><p>es - Іспанська</p><p>tr - Турецька</p><p>de - Німецька</p><p>it - Італійська</p><p>ru - Російська</p><p>zh - Китайська</p><p>fr - Французька</p><p>da - Данська</p><p>sv - Шведська</p><p>no - Норвезька</p><p>fi - Фінська</p><p>pl - Польська</p><p>ja - Японська</p><p>uk - Українська</p><p>be - Білоруська</p><p>ka - Грузинська</p><p>ro - Румунська</p></td></tr><tr><td><strong>payment_description</strong></td><td>опис платежу</td><td></td></tr><tr><td><strong>link_expired</strong> </td><td><p>час дії посилання на оплату, у форматі дд.мм.рррр (наприклад 25.06.2025). </p><p>За замовчуванням оплата має бути здійснена протягом 24 годин</p></td><td><p>Також можна в полі <strong>"Призначення змінних при переході"</strong> вказати: link_expired = current_date + 2 (посилання буде дійсним 2 дні до 00:00)</p><p><strong>link_expired</strong> так само можна вказати дату з точним часом, через пробіл, у форматі дд.мм.рррр гг:хх (наприклад: 25.06.2025 12:23). За замовчуванням оплата має бути здійснена протягом 24 годин</p><p>Також можна використовувати стандартні змінні, наприклад задамо час дії посилання 30 хвилин:</p><p>time = current_time + 30</p><p>link_expired = "#{current_date} #{time}"</p></td></tr><tr><td>russian_host</td><td>індикатор реєстрації магазину на російському хості bePaid. Вкажіть цей параметр зі значенням 1, якщо ваш магазин зареєстровано на сайті bepaid.tech</td><td>Якщо необхідно перемкнути хост на білоруський, вкажіть параметр зі значенням ''</td></tr><tr><td><strong>test_payments</strong></td><td>змінна потрібна для тестових платежів, якщо потрібен тестовий платіж, додайте її з будь-яким значенням.</td><td></td></tr><tr><td><strong>bepaid_attempts</strong> </td><td>вказує кількість спроб здійснити платіж, за замовчуванням дається 1 спроба.</td><td></td></tr><tr><td><strong>сustomer_data</strong></td><td>масив, що містить <em>first_name, last_name і email</em> платника. Дані необхідні для надсилання чека на пошту платника і доступні для редагування на сторінці оплати. </td><td><p>Параметр має бути переданий у вигляді списку у форматі json, що складається з пар ключ-значення</p><p><strong>наприклад</strong>:</p><p>customer_data = ‘{“first_name”: “Vladimir”, “last_name”: “Popov”, “email”: “v.popov@mavibot.ai” }’</p></td></tr><tr><td>bepaid_contract (умовно обов’язковий)</td><td>призначення платежу за токеном.</td><td>Очікувані значення: “recurring” (для регулярних оплат із заданою періодичністю) або “card_on_file” (для нерегулярних платежів, наприклад, післяплата за надану послугу)</td></tr></tbody></table>

Після завершення оплати клієнту буде додано змінну **bepaid\_callback\_data**, що містить дані відповіді платіжної системи щодо здійсненої операції. З отриманого словника можна витягти необхідні дані за допомогою методу **get**.

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

Для проведення тестового платежу до вказання змінної payment\_sum потрібно задати змінну test\_payments з будь-яким значенням.

Не забудьте прибрати її під час запуску бота в бойовому режимі!

Карти для тестів:

4200000000000000      успіх

4005550000000019        невдача

Якщо щось не працює, порівняйте дані з даними на офіційному сайті: <https://docs.bepaid.by/ru/test-integration#test-card-number>&#x20;

## Приклад формування посилання на оплату

Створимо посилання на оплату в розмірі 100 білоруських рублів (валюта за замовчуванням)

Зверніть увагу, спочатку задаємо додаткові змінні для налаштувань, потім payment\_sum. Змінні можна задати й раніше в ланцюжку, а не в одному блоці, це приклад.

Далі в потрібному місці виводимо змінну **bepaid\_pay\_url**, у якій міститься посилання

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

Інтеграція платіжної системи надає можливість створювати підписки для ваших клієнтів.

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

{% hint style="warning" %}
Якщо в особистому кабінеті не відображається меню “Плани” і “Підписки”, зверніться до вашого менеджера.
{% endhint %}

### Створення підписки та отримання посилання на оплату

Скористайтеся функцією **get\_bepaid\_subscription\_url**, передавши їй параметр plan\_id, де

<table><thead><tr><th width="233"></th><th></th></tr></thead><tbody><tr><td>plan_id</td><td>id плану в системі bePaid.</td></tr></tbody></table>

У результаті виконання функція створить підписку і поверне посилання на її оплату.

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

При успішній оплаті підписка активується, у угоду додадуться змінні bepaid\_subscription\_id і bepaid\_subscription\_status, а в бот надійде коллбек (див. розділ “[Як обробити результат](#kak-obrabotat-rezultat)”).

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

Щоб отримати дані поточної підписки клієнта, викличте функцію get\_bepaid\_subscription\_info, передавши їй параметр subscription\_id (значення можна взяти зі змінної bepaid\_subscription\_id).

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

Щоб скасувати підписку, використовуйте функцію cancel\_bepaid\_subscription.&#x20;

Ця функція приймає єдиний параметр subscription\_id (значення можна взяти зі змінної bepaid\_subscription\_id).

При успішному скасуванні змінна bepaid\_subscription\_status набуде значення “canceled”, а в бот надійде коллбек (див. розділ “[Як обробити результат](#kak-obrabotat-rezultat)”).

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

<table data-header-hidden><thead><tr><th width="270"></th><th></th></tr></thead><tbody><tr><td>trial</td><td>Активна або скасована підписка пробного періоду.</td></tr><tr><td>active</td><td>Активна підписка, платіж за якою було здійснено вчасно.</td></tr><tr><td>failed</td><td>Невдала підписка. bePaid не зміг провести черговий платіж.</td></tr><tr><td>error</td><td>Сталася помилка під час спроби bePaid провести платіж.</td></tr><tr><td>canceled</td><td>Підписку скасовано і вона більше не діє.</td></tr></tbody></table>

### Рекурентні платежі

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

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

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

До встановлення значення payment\_sum задайте змінну bepaid\_contract, у якій вкажіть призначення майбутніх платежів за токеном: “recurring” для регулярних оплат із заданою періодичністю або “card\_on\_file” для нерегулярних платежів (наприклад, післяплата за надану послугу).

{% hint style="warning" %}
Опція “card\_on\_file” підтримується не всіма еквайєрами. Якщо ви хочете її використовувати, зв’яжіться зі своїм акаунт-менеджером.
{% endhint %}

Після успішної оплати, в угоду буде додано змінну bepaid\_client\_card\_token, у якій збережеться токен картки клієнта. Цей токен дозволяє списувати кошти з картки клієнта без його участі.

Потім налаштуйте воронку і встановіть дату або умову для автоматичного списання та викличте функцію калькулятора make\_bepaid\_token\_payment, передавши їй необхідні параметри.

**Порядок слідування параметрів**:

amount -> currency -> description -> contract

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

<table><thead><tr><th width="286"></th><th></th></tr></thead><tbody><tr><td>amount (обов’язковий)</td><td>сума платежу, очікуване значення - ціле або десяткове число, наприклад 100 або 100.5;</td></tr><tr><td>currency (обов’язковий)</td><td>валюта оплати у<a href="http://en.wikipedia.org/wiki/ISO_4217"> ISO-4217</a> форматі, наприклад “USD”</td></tr><tr><td>description (обов’язковий)</td><td>опис причини списання, наприклад, “Оплата щотижневої підписки на участь у клубі за інтересами”;</td></tr><tr><td>contract (обов’язковий)</td><td>призначення платежу за токеном. Очікувані значення: “recurring” або “card_on_file”. </td></tr></tbody></table>

{% hint style="warning" %}
Значення contract обов’язково має відповідати значенню, вказаному під час створення посилання на установочний платіж!
{% endhint %}

Якщо платіж пройшов успішно, функція поверне повідомлення “Успішне списання за токеном bePaid“, ви отримаєте коллбек про успішну оплату, а змінна угоди bepaid\_token\_payment\_completed набуде значення “True”.

Якщо платіж не пройшов, функція поверне повідомлення із зазначенням причини невдалої оплати, в бот надійде коллбек із суфіксом “\_fail”, а змінна угоди bepaid\_token\_payment\_completed набуде значення “False”.

{% hint style="warning" %}
Банк може запросити завершення платежу клієнтом. У такому разі функція поверне посилання із запитом проходження аутентифікації 3-D Secure.
{% endhint %}

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

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

У системі коллбек виглядає як повідомлення від користувача, однак сам користувач його не бачить.

### Для оплат

У результаті оплати, що не стосується підписки, вам надійде одне з повідомлень:

<mark style="color:green;">**номерКлюча\_success**</mark> - при успішній оплаті;

<mark style="color:red;">**номерКлюча\_fail**</mark> - при невдалій оплаті;

Статус останньої оплати також можна відстежити за змінними bepaid\_payment\_completed (для оплат за участю клієнта) і bepaid\_token\_payment\_completed (для безакцептних оплат за токеном картки)

### Для підписок

Після успішної активації підписки під час першої або повторної оплати в бот надійде повідомлення <mark style="color:green;">**номерКлюча\_success**</mark>.

Якщо підписку було скасовано, ви отримаєте <mark style="color:orange;">**номерКлюча\_canceled**</mark>.

У разі невдалої оплати за підпискою вам надійде повідомлення *<mark style="color:red;">**номерКлюча**</mark>*<mark style="color:red;">\_fail.</mark>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mavibot.ai/doc/uk/integrations/payment/bepaid/bepaid-ru.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.