# Bepaid (ru)

## Как подключить

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

В MaviBot открываем раздел "Эквайринг", выбираем bePaid. Нужно ввести полученные данные.

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

Обратите внимание, что последнее поле является переключателем хостинга API в зависимости от страны пользования: Беларусь или Россия.

<div data-with-frame="true"><figure><img src="/files/f10ebd2b3c9a25dd1e542dd218e216c0df8d6dd2" 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:зелёный;">**номерКлюча\_success**</mark> — при успешной оплате;

<mark style="color:красный;">**номерКлюча\_fail**</mark> — при неудавшейся оплате;

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

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

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

Если подписка была отменена, вы получите <mark style="color:оранжевый;">**номерКлюча\_canceled**</mark>.

В случае неудавшейся оплаты по подписке вам придёт сообщение *<mark style="color:красный;">**номерКлюча**</mark>*<mark style="color:красный;">\_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/ru/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.