Подключение bePaid

bePaid — платёжный шлюз с приёмом карт Visa/Mastercard/«Мир», Apple Pay, Google Pay и белорусским ЕРИП. В 1С-Битрикс он подключается как обычная платёжная система: через модуль из Маркетплейса или собственный обработчик, а взаимодействие идёт по API с shop_id и секретным ключом.

Что такое bePaid и когда он нужен

bePaid — это платёжный агрегатор, популярный у продавцов, работающих на Беларусь и трансграничные продажи. Он закрывает сразу несколько сценариев оплаты: банковские карты Visa, Mastercard, «Мир», БЕЛКАРТ, кошельки Apple Pay и Google Pay, а также приём через белорусскую систему ЕРИП (для неё есть отдельный обработчик и отдельная статья).

Для покупателя оплата выглядит как переход на защищённую платёжную форму (checkout) с 3-D Secure либо как виджет на странице заказа. Для магазина bePaid работает по классической схеме: сайт формирует запрос на оплату, шлюз проводит транзакцию и возвращает статус, а факт успешной оплаты Битрикс получает серверным уведомлением.

Что подготовить перед подключением

Настройка на стороне Битрикс бессмысленна без доступов от bePaid. В личном кабинете (backoffice bePaid) после подписания договора вы получаете реквизиты магазина:

• Shop ID — числовой идентификатор магазина (кассы);
• Secret Key — секретный ключ для подписи запросов и проверки подписи уведомлений;
• адрес API/checkout шлюза, который прописывается в обработчике;
• тестовые реквизиты (отдельные shop_id и ключ для sandbox).

На стороне Битрикс потребуется установленный модуль sale (Интернет-магазин), настроенные статусы заказа и хотя бы один тип плательщика. Также заранее решите, какие типы плательщиков увидят bePaid — привязка платёжной системы к типу настраивается отдельно.

Модуль или собственный обработчик

У платёжной системы в Битрикс два пути реализации, и выбор влияет на дальнейшую поддержку.

Модуль ставится штатно через Marketplace → Установить решение и добавляет свой обработчик в список платёжных систем. Собственный обработчик — это папка с файлами в каталоге платёжных обработчиков; для новых заказов это структура вида /bitrix/php_interface/include/sale_payment/bepaid/ с файлами handler.php и описанием полей .description.php. В типовой связке заказов (order.php) обработчик регистрируется как отдельный тип платёжной системы.

Создание платёжной системы в админке

Идём в Магазин → Настройки → Платёжные системы и нажимаем «Добавить платёжную систему». Ключевые поля:

1. Название и код — например, «Оплата картой (bePaid)»;
2. Тип плательщика — отметьте тех, кому доступен способ (обычно «Физическое лицо»);
3. Обработчик — выберите обработчик bePaid из выпадающего списка;
4. в параметрах обработчика заполните Shop ID, Secret Key, валюту и режим работы (боевой/тестовый).

Проверьте настройки бизнес-значений: сумма заказа обычно берётся из PAYMENT_SHOULD_PAY, номер и описание платежа — из свойств заказа. Валюта платёжной системы должна совпадать с валютой заказа, иначе шлюз отклонит запрос. Если магазин многосайтовый, убедитесь, что платёжная система привязана к нужному сайту.

Уведомления об оплате (callback)

Статус заказа нельзя переводить в «оплачен» по факту возврата покупателя на сайт — браузер могут закрыть. Правильный источник истины — серверное уведомление bePaid (webhook/notification URL), которое шлюз отправляет напрямую на ваш обработчик.

• В личном кабинете bePaid укажите Notification URL — адрес, по которому Битрикс принимает уведомления (обычно скрипт результата платёжной системы);
• обработчик обязан проверять подпись уведомления по Secret Key — без этого возможна подделка статуса;
• после проверки сумма и номер заказа сверяются с заказом в базе, и только затем вызывается перевод оплаты (\Bitrix\Sale\Payment → setPaid).

Тестовый режим и приёмка

bePaid предоставляет sandbox с отдельными реквизитами и тестовыми картами. Перед запуском на боевом магазине пройдите полный цикл:

1. переведите платёжную систему в тестовый режим и подставьте тестовые shop_id и ключ;
2. оформите заказ и оплатите тестовой картой, включая сценарий 3-D Secure;
3. убедитесь, что пришёл webhook и заказ автоматически стал «оплачен»;
4. проверьте неуспешный сценарий — отказ карты не должен помечать заказ оплаченным.

Отдельно протестируйте возврат: если планируете возвраты через эквайринг, убедитесь, что обработчик умеет их инициировать или что процесс выстроен в кабинете bePaid. Только после успешной приёмки переключайте систему в боевой режим и меняйте реквизиты на продуктивные.

Диагностика типичных проблем

Если оплата не проходит или статус не обновляется, двигайтесь от простого к сложному:

• Ошибка подписи — перепроверьте Secret Key (не перепутан ли боевой и тестовый), кодировку и порядок полей при формировании подписи;
• Не приходит уведомление — проверьте, доступен ли Notification URL извне (нет ли закрытия по IP/basic-auth, отдаёт ли скрипт корректный HTTP-ответ);
• Несовпадение суммы/валюты — сверьте валюту платёжной системы и заказа, а также передачу суммы в минимальных единицах, если этого требует API;
• Заказ не переходит в «оплачен» — включите журналирование в обработчике и смотрите тело уведомления, а также Магазин → Настройки → Журнал и логи веб-сервера.

Полезно временно писать входящие уведомления в отдельный лог-файл: это быстрее всего показывает, доходит ли callback и какой статус в нём приходит.

Итог

Подключение bePaid к 1С-Битрикс сводится к трём шагам: получить shop_id и Secret Key, установить модуль или обработчик, создать платёжную систему и настроить проверку серверных уведомлений. Критичные места — подпись webhook и опора на callback, а не на redirect: именно здесь чаще всего теряются оплаты. Обязательно прогоните весь цикл в sandbox до боевого запуска.

Если нужен нестандартный сценарий — двухстадийные платежи, возвраты из админки, разные кассы под юрлиц и физлиц или связка с 1С — мы в B2Bsite настраиваем и дорабатываем платёжные интеграции на Битрикс под задачу и берём магазин на поддержку.