Bepaid

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

Чтобы подключить bePaid платёжную систему, вам понадобится Store ID, секретный ключ, и публичный ключ. Как только вы получите эти данные, перейдите в настройки в Salebot.

Чтобы получить Store ID, секретный ключ, и публичный ключ, пожалуйста, обратитесь в baPaid техническую поддержку за помощью.

В MaviBotоткройте «Платёжная система» раздел и выберите bePaid. Затем введите полученные данные.

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

Как сгенерировать ссылку на оплату

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

После того как переменная payment_sum задана, переменная bepaid_pay_url автоматически появится. Вы можете вывести эту переменную на экран как ссылку или разместить её на кнопке с текстом «Оплатить».

Ссылка на оплату будет выглядеть так: https://checkout.bepaid.by/widget/hpp.html?token=a05eabd3f9368725efbc175614c7d469da08f198cc51916b07fb75e53f9a3e1a

Перед установкой переменной payment_sum вы также можете задать следующие необязательные переменные для настройки оплаты.

По умолчанию валюта установлена на белорусский рубль. Если вам нужно использовать другую валюту, задайте значение для переменной currency .

Параметры функции	Описание	Дополнительная информация
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 часов.	Вы также можете использовать поле «Assign Variables on Redirect» для установки: link_expired = current_date + 2 — ссылка будет действительна 2 дня до 00:00. Вы также можете указать точную дату и время истечения в формате дд.мм.гггг чч:мм (например: 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	Массив, содержащий имя, фамилию, и emailплательщика. Эти данные необходимы для отправки чека на email плательщика и могут быть отредактированы на странице оплаты.	Параметр должен передаваться как список пар ключ-значение в формате JSON. Например: customer_data = ‘{“first_name”: “Sam”, “last_name”: “Smith”, “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 в нужном месте; она содержит сгенерированную ссылку на оплату.

Управление подписками

Интеграция с платёжной системой позволяет создавать подписки для ваших клиентов.

Перед использованием этой функции в Salebotсоздайте план подписки в вашем bePaid аккаунте.

Если «Планы» и «Подписки» меню не отображаются в вашем аккаунте, пожалуйста, обратитесь к вашему менеджеру.

Создание подписки и генерация ссылки на оплату

Используйте get_bepaid_subscription_url функцию, передав plan_id параметр, где…

plan_id	plan_id — это ID плана в bePaid системе.

В результате функция создаст подписку и вернёт ссылку на оплату.

Отправьте ссылку клиенту и дождитесь завершения оплаты.

После успешной оплаты подписка будет активирована. В сделке появятся переменные 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 (см. «Как обработать результат» ).

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

trial	Активна или отменена пробный период подписки.
active	Активная подписка с платежом, выполненным вовремя.
failed	Ошибка в подписке. bePaid не удалось обработать следующий платёж.
error	Произошла ошибка при bePaid пыталась обработать платёж.
canceled	Подписка была 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”, вы получите callback об успешной оплате, а переменная сделки bepaid_token_payment_completed будет установлена в “True”.

Если платёж не пройдёт, функция вернёт сообщение с причиной неудачной оплаты, в бота будет отправлен callback с суффиксом “_fail” , а переменная сделки bepaid_token_payment_completed будет установлена в “False”.

Банк может потребовать от клиента завершить платёж. В этом случае функция вернёт ссылку, предлагающую клиенту пройти аутентификацию 3-D Secure.

Как обработать результат

В ответ на действия клиента бот получит callbacks, состоящие из первых 20 символов секретного ключа и суффикса, который зависит от типа и результата операции.

В системе callback отображается как сообщение от пользователя, но пользователь не видит его.

Для платежей

Для платежей не связанных с подписками, вы получите одно из следующих сообщений:

• keyNumber_success – при успешном платеже

• keyNumber_fail – при неуспешном платеже

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

• bepaid_payment_completed – для платежей с участием клиента

• bepaid_token_payment_completed – для автоматических платежей по токену карты

Для подписок

После успешной активации подписки, как при первом, так и при повторном платеже, бот получит сообщение keyNumber_success.

Если подписка отменена, вы получите keyNumber_canceled.

В случае неуспешного платежа по подписке сообщение keyNumber_fail будет отправлено.