CloudPayments: подключение

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

Что такое CloudPayments и когда он уместен

CloudPayments — интернет-эквайринг, который работает поверх банка-партнёра и отдаёт магазину удобные инструменты приёма платежей: виджет оплаты (форма прямо на странице без ухода на сторонний домен), классический redirect на защищённую страницу и полноценный REST API. Для интернет-магазина на 1С-Битрикс это один из самых гибких вариантов, особенно если нужны подписки и списания без повторного ввода карты.

• Карты Visa, Mastercard, МИР с поддержкой 3-D Secure 2.0;
• СБП по QR и по кнопке;
• Рекуррентные платежи (подписки, автопродление) по сохранённому токену;
• Фискализация чеков по 54-ФЗ через встроенную кассу (CloudKassir) или сторонний ОФД;
• Быстрые кошельки: Apple Pay / Google Pay там, где они доступны.

Регистрация и ключи доступа

Перед интеграцией магазин заключает договор с CloudPayments и получает доступ в личный кабинет. Оттуда берутся два ключевых значения, которые понадобятся в настройках Битрикса.

Два способа интеграции с Битриксом

На практике интегратор выбирает между готовым модулем и собственным обработчиком. Оба варианта рабочие, разница в гибкости и объёме поддержки.

1. Модуль из Маркетплейса 1С-Битрикс. CloudPayments и партнёры публикуют платёжные модули, которые ставятся стандартно и добавляют новый платёжный обработчик в разделе Магазин → Платёжные системы. Быстро, но кастомизация ограничена возможностями модуля.
2. Свой обработчик платёжной системы. Создаётся в /bitrix/php_interface/include/sale_payment/ (или в собственном модуле) с файлами .description.php и payment/template.php. Такой подход даёт полный контроль над виджетом, чеком и логикой вебхуков.

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

Виджет оплаты на странице

Ключевое преимущество CloudPayments — оплата без ухода с сайта. На страницу подключается скрипт виджета, а по кнопке вызывается объект cp.CloudPayments() с параметрами заказа.

Подключение библиотеки:

<script src="https://widget.cloudpayments.ru/bundles/cloudpayments.js"></script>

Вызов оплаты (сумма, номер заказа и данные для чека обязательно приходят с сервера, а не формируются на клиенте):

var widget = new cp.CloudPayments(); widget.pay('charge', {publicId: PUBLIC_ID, description: 'Заказ №'+orderId, amount: amount, currency: 'RUB', invoiceId: orderId, accountId: userEmail, data: {cloudPayments: {}}});

Вебхуки и смена статуса заказа

Статус оплаты в Битриксе меняет не браузер покупателя, а серверные уведомления CloudPayments (webhooks). Магазин указывает их URL в личном кабинете, а обработчик проверяет подпись и переводит заказ в оплаченный.

Подлинность вебхука проверяется по заголовку Content-HMAC: сервер считает HMAC-SHA256 от тела запроса на API Secret и сверяет с присланным значением. В ответ CloudPayments ждёт JSON {"code": 0} — иначе уведомление будет повторяться.

Фискализация и рекуррентные платежи

По 54-ФЗ на каждую онлайн-оплату нужен фискальный чек. У CloudPayments есть два пути: передавать чек через их встроенную кассу либо подключить свою кассу/ОФД и отправлять данные позиций вместе с платежом в объекте Receipt.

• Позиции чека (наименование, количество, цена, ставка НДС, признак предмета и способа расчёта) должны совпадать с составом заказа в Битриксе;
• Ставку НДС берём из свойств товара/торгового каталога, а не хардкодим;
• Для предоплаты и полной оплаты формируются разные признаки способа расчёта.

Рекуррентные списания строятся на токене: при первой оплате CloudPayments возвращает Token, который сохраняется на стороне магазина и используется для последующих списаний через API /payments/tokens/charge. Это база для подписок, автопополнений и продлений доступа.

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

Перед боевым запуском связку прогоняют в тестовом режиме и на тестовых картах CloudPayments. Мы проверяем полный цикл: создание заказа, оплату, приход вебхука, смену статуса и формирование чека.

• Заказ не оплачивается по факту списания — не настроен или не отвечает вебхук: проверьте доступность URL и ответ {"code":0};
• Подпись не сходится — тело запроса читается уже изменённым: HMAC считайте от «сырого» body (php://input) до любых преобразований;
• Двойное проставление оплаты — нет идемпотентности: обрабатывайте TransactionId и не платите повторно по тому же событию;
• Чек не уходит в ОФД — некорректные позиции или ставка НДС в Receipt.

Итог

Подключение CloudPayments к 1С-Битрикс сводится к четырём вещам: получить Public ID и API Secret, вывести виджет или redirect на оплату, замкнуть вебхуки на смену статуса заказа с проверкой HMAC-подписи и настроить фискализацию чеков. Если нужны подписки — добавляется хранение токена и рекуррентные списания. Ошибки обычно живут не в оплате, а в вебхуках и составе чека, поэтому мы всегда закладываем идемпотентность и логирование.

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