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

PayKeeper — это платёжный сервис, который подключает эквайринг банка к вашему сайту и берёт на себя приём карт, СБП и фискализацию. В 1С-Битрикс он работает как отдельный обработчик платёжной системы: покупатель уходит на защищённую форму PayKeeper, а магазин узнаёт об оплате через обратный вызов. Ниже — практическая схема подключения без лишней теории.

Что такое PayKeeper и как он работает с Битрикс

PayKeeper — это не банк, а процессинговый шлюз: он стоит между вашим сайтом и банком-эквайером, формирует платёжную форму, принимает карты, СБП и электронные кошельки, а деньги банк зачисляет на ваш расчётный счёт. Для магазина на 1С-Битрикс это означает, что реквизиты карты покупатель вводит на стороне PayKeeper, а не на вашем домене — сайту не нужен сертификат PCI DSS.

Схема обмена стандартная для внешних платёжных систем в Битрикс:

• покупатель оформляет заказ и выбирает способ оплаты PayKeeper;
• Битрикс формирует запрос с суммой и номером заказа и перенаправляет пользователя на форму оплаты вида https://company.server.paykeeper.ru/order/;
• после оплаты PayKeeper отправляет на сайт обратный вызов (callback) с параметрами платежа и подписью;
• обработчик проверяет подпись и переводит заказ в статус «оплачен».

Подготовка: личный кабинет и параметры

До настройки Битрикс подготовьте доступы и параметры в личном кабинете PayKeeper (раздел Настройки → Получение информации о платежах и Настройки → СМС/e-mail информирование). Ключевые значения, которые понадобятся на стороне сайта:

Договоритесь с менеджером PayKeeper о способе интеграции: форма оплаты POST (самый распространённый вариант для Битрикс) или API-инициация платежа. Для большинства магазинов достаточно формы. Также заранее уточните кодировку — Битрикс-магазин чаще работает в UTF-8, и в кабинете должна стоять та же кодировка, иначе кириллица в наименовании товара «поедет».

Установка обработчика в Битрикс

PayKeeper не входит в стандартную поставку 1С-Битрикс, поэтому обработчик добавляется одним из двух способов:

1. Готовый модуль из Маркетплейса. PayKeeper распространяет официальное решение; после установки в Marketplace → Установленные решения обработчик появляется в списке платёжных систем автоматически.
2. Ручной обработчик. Файлы кладутся в каталог обработчиков платёжных систем: в старой модели заказа это /bitrix/php_interface/include/sale_payment/paykeeper/ с файлами .description.php и payment.php; в новой модели заказа (Sale, D7) — пользовательский платёжный шлюз, привязанный к платёжной системе.

Проверьте редакцию продукта: платёжные системы доступны в редакциях со «Стандартом» и выше (в первую очередь «Малый бизнес» и «Бизнес»). В «Старте» модуля интернет-магазина нет.

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

Перейдите в Магазин → Настройки → Платёжные системы (в новой модели — Магазин → Способы оплаты) и создайте платёжную систему на базе обработчика PayKeeper. Заполните бизнес-настройки обработчика:

• Адрес формы оплаты — поддомен вашего кабинета PayKeeper;
• Секретное слово — то же значение, что в кабинете, для подписи формы;
• Секретный ключ обратного вызова — для проверки callback;
• Поля соответствия — сумма заказа (PAYMENT_SHOULD_PAY или свойство заказа), e-mail и телефон покупателя из свойств заказа.

Привяжите платёжную систему к нужному типу плательщика (например, «Физическое лицо»), иначе покупатель не увидит способ оплаты на шаге выбора. Если магазин многосайтовый, убедитесь, что платёжная система активна для нужного сайта. Сумма и валюта передаются из заказа автоматически, но проверьте, что валюта заказа совпадает с валютой, настроенной в договоре PayKeeper.

Обратный вызов и подтверждение оплаты

Ключевой момент интеграции — обратный вызов. Без него заказ никогда не станет «оплаченным», даже если деньги прошли. В личном кабинете PayKeeper в настройках обратных вызовов укажите URL вашего обработчика, например https://вашсайт.ru/bitrix/tools/sale_ps_result.php или адрес пользовательского скрипта, который принимает POST.

Логика приёма callback:

1. PayKeeper шлёт POST с параметрами id, sum, orderid, clientid и подписью;
2. обработчик пересчитывает подпись по секретному ключу и сверяет её — при несовпадении запрос отклоняется;
3. сверяется сумма платежа с суммой заказа, заказ помечается оплаченным;
4. в ответ обработчик обязан вернуть строку вида OK md5-хэш — только тогда PayKeeper считает уведомление доставленным и не повторяет его.

Фискализация по 54-ФЗ

Приём онлайн-оплаты в России требует пробития кассового чека по 54-ФЗ. PayKeeper поддерживает подключение онлайн-кассы и передачу чека при платеже, поэтому в большинстве случаев фискализация настраивается на стороне сервиса, а не в Битрикс.

Чтобы чек был корректным, магазин должен передать состав заказа: наименование позиций, количество, цену, ставку НДС и признак предмета расчёта. Здесь есть выбор:

• передавать позиции из формы оплаты Битрикс, если обработчик это поддерживает;
• или пробивать чек по данным, которые PayKeeper получает в запросе.

Отдельно проверьте ставки НДС в товарах каталога: расхождение ставки в карточке товара и в чеке — частая причина отказа ОФД.

Тестирование и типичные ошибки

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

Смотрите журнал в Магазин → Настройки → Журнал и историю обратных вызовов в кабинете PayKeeper — они быстро показывают, на каком шаге рвётся цепочка. Если планируете возвраты, отдельно настройте API-доступ: возврат инициируется запросом к PayKeeper, а не кнопкой «отменить» в заказе.

Итог

Подключение PayKeeper к 1С-Битрикс сводится к четырём вещам: получить параметры в личном кабинете, установить обработчик, настроить платёжную систему с секретным словом и корректно принять обратный вызов с проверкой подписи и суммы. Отдельно продумайте фискализацию по 54-ФЗ и обязательно протестируйте реальный платёж до открытия продаж.

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