# Bepaid

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

Щоб підключити **bePaid** платіжну систему, вам знадобиться **Store ID**, **секретний ключ**, і **публічний ключ**. Після того як ви отримаєте ці облікові дані, перейдіть до налаштувань у **Salebot**.

{% hint style="info" %}
Щоб отримати **Store ID**, **секретний ключ**, і **публічний ключ**, будь ласка, зверніться до **baPaid** технічної підтримки за допомогою.
{% endhint %}

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

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

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

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

## **Як згенерувати платіжне посилання**

Щоб згенерувати платіжне посилання, потрібно задати значення для змінної **payment\_sum** (наприклад: **150** або **100.55** — як десятковий роздільник використовуйте крапку).

Після того як **payment\_sum** змінну буде встановлено, **bepaid\_pay\_url** змінна автоматично з’явиться. Ви можете відобразити цю змінну на екрані як посилання або помістити її на кнопку з текстом **"Оплатити"**.

Платіжне посилання матиме такий вигляд:\
<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>Валюта платежу у форматі ISO 4217</td><td>Наприклад: <strong>USD</strong></td></tr><tr><td><strong>language</strong></td><td><strong>Мова платіжної сторінки</strong><br>За замовчуванням: <strong>en</strong>.</td><td><p><strong>Дозволені значення:</strong></p><ul><li><strong>en</strong> – англійська</li><li><strong>es</strong> – іспанська</li><li><strong>tr</strong> – турецька</li><li><strong>de</strong> – німецька</li><li><strong>it</strong> – італійська</li><li><strong>ru</strong> – російська</li><li><strong>zh</strong> – китайська</li><li><strong>fr</strong> – французька</li><li><strong>da</strong> – датська</li><li><strong>sv</strong> – шведська</li><li><strong>no</strong> – норвезька</li><li><strong>fi</strong> – фінська</li><li><strong>pl</strong> – польська</li><li><strong>ja</strong> – японська</li><li><strong>uk</strong> – українська</li><li><strong>be</strong> – білоруська</li><li><strong>ka</strong> – грузинська</li><li><strong>ro</strong> – румунська</li></ul></td></tr><tr><td><strong>payment_description</strong></td><td>Опис платежу</td><td></td></tr><tr><td><strong>link_expired</strong> </td><td><strong>Термін дії платіжного посилання</strong><br>Встановіть дату закінчення у форматі <strong>дд.мм.рррр</strong> (наприклад: <strong>25.06.2025</strong>).<br>За замовчуванням платіж потрібно завершити протягом <strong>24 годин</strong>.</td><td><p>Ви також можете використати <strong>"Призначити змінні при редиректі"</strong> поле, щоб встановити:</p><ul><li><code>link_expired = current_date + 2</code> — посилання буде дійсним <strong>2 дні до 00:00</strong>.</li><li>Ви також можете вказати точну дату й час закінчення у форматі <strong>дд.мм.рррр гг:хв</strong> (наприклад: <strong>25.06.2025 12:23</strong>). За замовчуванням платіж потрібно завершити протягом <strong>24 годин</strong>.</li></ul><p>Також можна використовувати стандартні змінні. Наприклад, щоб встановити термін дії посилання на <strong>30 хвилин</strong>:<br>time = current_time + 30<br>link_expired = "#{current_date} #{time}"</p></td></tr><tr><td>russian_host</td><td><strong>Індикатор для магазину, зареєстрованого на російському хості bePaid</strong><br>Встановіть цей параметр у <strong>1</strong> якщо ваш магазин зареєстровано на <strong>bepaid.tech</strong>.</td><td>Якщо потрібно перемкнути хост на Білорусь, встановіть цей параметр у <strong>""</strong> (порожнє значення).</td></tr><tr><td><strong>test_payments</strong></td><td>Ця змінна використовується для <strong>тестових платежів</strong>. Щоб виконати тестовий платіж, додайте її з будь-яким значенням.</td><td></td></tr><tr><td><strong>bepaid_attempts</strong> </td><td>Визначає <strong>кількість спроб платежу</strong>. За замовчуванням <strong>1 спроба</strong> дозволена.</td><td></td></tr><tr><td><strong>сustomer_data</strong></td><td>Масив, що містить <strong>ім’я</strong>, <strong>прізвище</strong>, і <strong>email</strong>платника. Ці дані потрібні для надсилання квитанції на email платника і можуть бути змінені на платіжній сторінці.</td><td>Параметр має передаватися як <strong>список пар ключ-значення у форматі JSON</strong>.<br>Наприклад:<br>customer_data = ‘{“first_name”: “Sam”, “last_name”: “Smith”, “email”: “sam_smith@mavibot.ai” }’</td></tr><tr><td><strong>bepaid_contract</strong> (умовно обов’язково)</td><td>Призначення платежу за токеном</td><td><p><strong>Очікувані значення:</strong></p><ul><li><strong>“recurring”</strong> – для регулярних платежів із заданою періодичністю</li><li><strong>“card_on_file”</strong> – для одноразових або нерегулярних платежів, наприклад, післяплати за послугу</li></ul></td></tr></tbody></table>

Після завершення платежу **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** змінну в потрібному місці; вона містить згенероване платіжне посилання.

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

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

Перед використанням цієї функції в **Salebot**створіть тарифний план у своєму **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><strong>plan_id</strong> — це ID плану в <strong>bePaid</strong> системі.</td></tr></tbody></table>

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

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

Після успішного платежу підписку буде активовано. У угоду буде додано **bepaid\_subscription\_id** та **bepaid\_subscription\_status** змінні, а до бота буде надіслано callback (див. розділ **“Як обробити результат”** ).

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

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

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

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

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

Після успішного скасування **bepaid\_subscription\_status** змінна буде встановлена у **“canceled”**, а до бота буде надіслано callback (див. розділ **“Як обробити результат”** ).

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

<table data-header-hidden><thead><tr><th width="270"></th><th></th></tr></thead><tbody><tr><td>trial</td><td>Активна або скасована <strong>триального періоду</strong> підписка.</td></tr><tr><td>active</td><td>Активна підписка з <strong>своєчасно здійсненим платежем</strong>.</td></tr><tr><td>failed</td><td>Невдала підписка. <strong>bePaid</strong> не вдалося обробити наступний платіж.</td></tr><tr><td>error</td><td>Сталася помилка під час <strong>bePaid</strong> спроби обробити платіж.</td></tr><tr><td>canceled</td><td>Підписку було <strong>canceled</strong> і вона більше не активна.</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><strong>Сума платежу</strong> – очікуване значення — це <strong>ціле</strong> або <strong>десяткове число</strong>, наприклад: 100 або 100.5.</td></tr><tr><td>currency (обов’язково)</td><td><strong>Валюта платежу</strong> у <strong>ISO 4217</strong> форматі, наприклад: <strong>“USD”</strong>.</td></tr><tr><td>description (обов’язково)</td><td><strong>Опис списання</strong>, наприклад: <strong>“Щотижневий платіж за підпискою для участі в гуртку за інтересами”</strong>.</td></tr><tr><td>contract (обов’язково)</td><td><strong>Призначення платежу за токеном.</strong> Очікувані значення: <strong>“recurring”</strong> або <strong>“card_on_file”</strong>.</td></tr></tbody></table>

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

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

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

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

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

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

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

### **Для платежів**

Для платежів **не пов’язаних із підписками**, ви отримаєте одне з таких повідомлень:

* **keyNumber\_success** – для успішного платежу
* **keyNumber\_fail** – для невдалого платежу

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

* **bepaid\_payment\_completed** – для платежів за участю клієнта
* **bepaid\_token\_payment\_completed** – для **автоматичних платежів за токеном картки**

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

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

Якщо підписку скасовано, ви отримаєте **keyNumber\_canceled**.

У разі невдалого платежу за підпискою буде надіслано повідомлення **keyNumber\_fail** .


---

# 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.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.