Как подключить
Для подключения платежной системы bePaid вам потребуется ID магазина, секретный ключ и публичный ключ. После их получения переходим к настройкам в Salebot.
В Salebot открываем раздел «Эквайринг», выбираем bePaid. Нужно ввести полученные данные.
Обратите внимание, что последнее поле является переключателем хостинга API в зависимости от страны пользования: Беларусь или Россия.
Как сформировать ссылку на оплату
Для генерации ссылки на оплату вам необходимо установить значение переменной payment_sum (например 150 или 100.55 (через точку!)), сразу после этого появится переменная bepaid_pay_url.
Эту переменную можно вывести на экран ссылкой или разместить на кнопке с текстом «Оплатить».
Ссылка имеет вид:
Также до установки значения переменной 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 часов. |
Также можно в поле «Назначение переменных при переходе» указать: link_expired = current_date + 2 (ссылка будет действительна 2 дня до 00:00).link_expired также можно указать дату с точным временем через пробел в формате дд.мм.гггг чч:мм (например 25.06.2025 12:23). По умолчанию оплата должна быть сделана в течение 24 часов.Также можно использовать стандартные переменные, например: time = current_time + 30link_expired = "#{current_date} #{time}"
|
russian_host |
индикатор регистрации магазина на российском хосте bePaid. Укажите данный параметр со значением 1, если ваш магазин зарегистрирован на сайте bepaid.tech. |
Если необходимо переключить хост на белорусский, укажите параметр со значением ''. |
test_payments |
переменная нужна для тестовых платежей. Если нужен тестовый платеж — добавить с любым значением. | |
bepaid_attempts |
указывает количество попыток совершить платеж. По умолчанию дается 1 попытка. | |
customer_data |
массив, содержащий first_name, last_name и email плательщика. Данные необходимы для отправки чека на почту плательщика и доступны для редактирования на странице оплаты. |
Параметр должен быть передан в виде JSON. Например: customer_data = '{"first_name":"Vladimir","last_name":"Popov","email":"v.popov@salebot.pro"}'
|
bepaid_contract (условно обязательный) |
назначение платежа по токену | Ожидаемые значения: "recurring" (для регулярных оплат с заданной периодичностью) или "card_on_file" (для нерегулярных платежей, например постоплата за оказанную услугу) |
После завершения оплаты клиенту добавится переменная bepaid_callback_data, содержащая данные ответа платежной системы по совершенной операции.
Из полученного словаря можно извлечь необходимые данные при помощи метода get.
Как тестировать платежи
Для проведения тестового платежа до указания переменной payment_sum нужно задать переменную test_payments с любым значением.
Не забудьте убрать ее при запуске бота в боевом режиме!
Карты для тестов:
4200000000000000 success
4005550000000019 failed
Если что-то не работает, сравните данные с официальной документацией:
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 |
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