PayKeeper — это платёжный шлюз, который часто разворачивается под конкретный банк-эквайер и работает на выделенном сервере магазина. Для 1С-Битрикс он подключается готовым модулем или обработчиком платёжной системы, а вся надёжность держится на секретном слове и корректной проверке подписи в callback об оплате.
Что такое PayKeeper и его особенность
PayKeeper — это процессинговый шлюз для приёма онлайн-платежей, который банки-партнёры предоставляют своим клиентам. Его отличие от классических агрегаторов в том, что магазин обычно получает собственный поддомен-сервер вида yourshop.server.paykeeper.ru, через который проходят все операции: создание счёта, оплата, уведомления и возвраты.
- Приём карт Visa, Mastercard, МИР с 3-D Secure;
- Приём по СБП (если включено банком);
- Фискализация чеков по 54-ФЗ через интегрированную кассу;
- Личный кабинет с реестром платежей и возвратами;
- Настройка внешнего вида платёжной страницы.
Доступы и параметры интеграции
Перед настройкой Битрикса от банка/PayKeeper нужно получить реквизиты интеграции. Их немного, но каждый критичен для работы подписи.
| Параметр | Назначение |
|---|---|
Адрес сервера | Домен вида *.server.paykeeper.ru для форм и API |
Секретное слово | Общий секрет для расчёта и проверки подписи (seed) |
Логин/пароль ЛК | Доступ в личный кабинет, реестр, возвраты |
| URL callback | Адрес вашего обработчика для уведомлений об оплате |
Способы подключения к Битриксу
Для 1С-Битрикс есть два основных пути. Оба заканчиваются появлением нового обработчика в разделе Магазин → Платёжные системы.
- Готовый модуль PayKeeper из Маркетплейса. Ставится штатно, добавляет платёжную систему и поля для адреса сервера и секретного слова. Оптимально для типовых магазинов.
- Свой обработчик платёжной системы. Создаётся в
/bitrix/php_interface/include/sale_payment/paykeeper/с файлами.description.php(настройки: сервер, секрет) иpayment/template.php(форма/редирект на оплату). Даёт контроль над составом чека и статусами.
Мы выбираем модуль, когда магазин типовой, и собственный обработчик, когда есть мультиюрлица, сложная фискализация или нужен точный контроль позиций чека.
Как проходит оплата: счёт и редирект
Сценарий приёма платежа в PayKeeper строится вокруг счёта. Есть два подхода: отправить покупателя на платёжную форму сервера с параметрами заказа или предварительно создать счёт по API и получить ссылку на оплату.
- Форма/редирект. Магазин формирует запрос на
https://yourshop.server.paykeeper.ru/create/или отдаёт форму с суммой, номером заказа, email/телефоном плательщика и подписью; - API-счёт. Метод предпросмотра/создания счёта
/change/invoice/preview/возвращает идентификатор и ссылку, которую можно отправить клиенту.
Сумму, номер заказа и данные для чека всегда формирует сервер магазина на основе заказа в Битриксе — фронту доверять нельзя. После оплаты покупатель возвращается на success-страницу, но фактический статус ставит только серверный callback.
Callback об оплате и проверка подписи
Смена статуса заказа в Битриксе выполняется по серверному уведомлению PayKeeper. Обработчик обязан проверить подпись, сверить сумму и только затем проставить оплату.
Подпись обычно считается как MD5 от конкатенации параметров и секретного слова, например: md5($id . $sum . $clientid . $orderid . $secret_seed). Сервер сверяет вычисленное значение с присланным полем подписи.
- Принять POST callback от сервера PayKeeper;
- Пересчитать подпись по секретному слову и сравнить с полученной;
- Сверить сумму и номер заказа с реальным заказом в Битриксе;
- Проставить оплату (
Payment::setPaid('Y')) и вернуть ответ видаOK idс ключом подтверждения.
Фискализация и возвраты
PayKeeper поддерживает фискализацию по 54-ФЗ: чек формируется на стороне шлюза при подключённой кассе. Магазин передаёт состав чека вместе с параметрами платежа — наименование позиций, количество, цену, ставку НДС и признаки предмета/способа расчёта.
| Операция | Где выполняется | Отражение в Битриксе |
|---|---|---|
| Оплата | Сервер PayKeeper | Callback → статус «оплачен» |
| Возврат | ЛК PayKeeper или API | Отмена оплаты по заказу |
| Чек прихода | Касса шлюза | Данные позиций из заказа |
- Состав чека должен совпадать с позициями заказа, иначе возможны расхождения с ОФД;
- Ставку НДС берём из свойств торгового каталога;
- Возврат по 54-ФЗ формирует чек возврата — учитывайте это при частичных возвратах.
Тестирование и частые проблемы
Перед запуском связку проверяют на тестовом контуре банка. Мы прогоняем полный путь: заказ → оплата → callback → статус → чек, а также сценарий возврата.
- Заказ не переходит в «оплачен» — callback недоступен извне или не отвечает нужным ключом подтверждения;
- Подпись не совпадает — неверный порядок полей в конкатенации или лишние пробелы; сверьтесь с документацией по конкретной версии шлюза;
- Неверная сумма в чеке — рассинхрон позиций заказа и передаваемого чека;
- Оплата ставится дважды — нет защиты от повторного callback по одному платежу.
Итог
Подключение PayKeeper к 1С-Битрикс держится на трёх опорах: адрес сервера магазина, секретное слово и корректная проверка подписи в callback. Оплата инициируется формой или API-счётом, а фактический статус заказа ставит только серверное уведомление после сверки суммы. Фискализация и возвраты выполняются на стороне шлюза, но состав чека приходит из заказа в Битриксе, поэтому за синхронностью позиций надо следить.
Мы подключаем PayKeeper и другие банковские шлюзы к магазинам на Битриксе: настраиваем обработчик, подписи, callback, фискализацию и возвраты, а при нетиповой корзине пишем собственный платёжный обработчик. Если ваш банк выдал сервер PayKeeper и нужно аккуратно завести оплату на сайт — поможем внедрить и протестировать связку до боевого запуска.
Частые вопросы
Почему у PayKeeper отдельный сервер для магазина?
PayKeeper часто разворачивается под конкретный банк-эквайер, и магазин получает выделенный поддомен вида yourshop.server.paykeeper.ru. Через него проходят формы оплаты, API и уведомления.
Что нужно от банка для подключения?
Адрес сервера магазина, секретное слово для подписи, доступ в личный кабинет и согласованный URL callback. Секретное слово критично — оно участвует в проверке подлинности уведомлений.
Как PayKeeper подключается к 1С-Битрикс?
Либо готовым модулем из Маркетплейса, который добавляет платёжную систему, либо собственным обработчиком в /bitrix/php_interface/include/sale_payment. Второй путь даёт контроль над чеком и статусами.
Как считается подпись callback?
Обычно это MD5 от конкатенации параметров платежа и секретного слова. Обработчик пересчитывает подпись и сравнивает с присланной, и только затем проставляет оплату.
Кто формирует фискальный чек?
Чек по 54-ФЗ формируется на стороне PayKeeper при подключённой кассе, а состав позиций магазин передаёт из заказа. Наименования и ставки НДС должны совпадать с заказом в Битриксе.
Можно ли делать возвраты?
Да, возврат выполняется из личного кабинета PayKeeper или по API, при этом по 54-ФЗ формируется чек возврата. В Битриксе это отражается отменой оплаты по заказу.
Поддерживается ли оплата по СБП?
Оплата по СБП возможна, если она включена банком в вашем тарифе PayKeeper. Способ настраивается на стороне шлюза, а статус приходит тем же callback.
Что делать, если оплата не проставляется?
Чаще всего callback недоступен извне или отвечает не тем ключом подтверждения. Проверьте доступность URL обработчика, ответ серверу и корректность проверки подписи.
Поможем с настройкой и поддержкой Интеграции и связки систем
Поможем с настройкой, доработкой и поддержкой Интеграции и связки систем.