Виджет CloudPayments и Public ID: настройка платежной формы шаг за шагом
Что такое CloudPayments виджет и Public ID
CloudPayments виджет — это готовая платежная форма, которую легко встроить на сайт или в веб-приложение. Он поддерживает карты, токенизацию, 3‑D Secure, а также дополнительные способы оплаты, включая СБП. В документации и поисковых запросах вы можете встретить формулировки вроде «widget cloudpayments», «cloudpayments виджет» или «widget cloudpayments ru» — речь всегда про один и тот же модуль оплаты.
Public ID — это публичный идентификатор вашего магазина в CloudPayments. Он передается на клиентской стороне и нужен виджету, чтобы понять, на какой мерчант и на какой контракт инициировать платеж. Не путайте Public ID с секретным ключом — секрет хранится только на вашем сервере и используется для формирования подписи.
Подробнее о самой системе и возможностях сервиса читайте в материале что такое CloudPayments.
Где найти Public ID в личном кабинете
Чтобы настроить cloudpayments виджет, сначала получите Public ID:
- Зайдите в личный кабинет CloudPayments. Если еще не подключены — посмотрите пошаговый гайд как подключить CloudPayments.
- Перейдите в раздел «Настройки» → «Интеграция» в вашем My CloudPayments (личный кабинет).
- Скопируйте значение Public ID. Для продакшна используйте боевой Public ID, а для тестов — тестовый.
- Проверьте, что домены, с которых грузится виджет, добавлены в список разрешенных источников (если политика безопасности это требует).
Варианты отображения виджета
CloudPayments виджет гибко встраивается в интерфейс:
- Модальное окно: наиболее быстрый способ — форма появляется поверх страницы.
- Встраиваемый блок: виджет размещается в контенте страницы (например, в колонке заказа).
- Однокнопочная оплата: открытие формы по нажатию кнопки «Оплатить».
- Рекуррентные списания и токенизация: сохранение карты для будущих платежей.
Таблица выбора сценария:
| Сценарий |
Когда использовать |
Плюсы |
Минусы |
| Модальный виджет |
Обычные разовые платежи |
Быстрый старт, минимум кода |
Требует JS |
| Встроенная форма |
Макс. контроль над UI |
Бесшовный UX |
Чуть сложнее верстка |
| Ссылка на оплату |
Нет разработчика или JS |
Запуск за минуты |
Меньше контроля над UX |
| Подписки/токены |
Регулярные списания |
Повышает LTV, меньше трения |
Нужна серверная часть |
Быстрый старт: минимальная интеграция
Ниже — базовый алгоритм, как добавить widget CloudPayments на страницу и инициировать оплату.
- Подключите скрипт виджета:
<script src="https://widget.cloudpayments.ru/bundles/cloudpayments"></script>
- Добавьте кнопку оплаты и обработчик:
<button id="payBtn">Оплатить</button>
<script>
document.getElementById('payBtn').addEventListener('click', function () {
var widget = new cp.CloudPayments();
widget.pay('charge', // charge = разовый платеж, auth = двухстадийный
{
publicId: 'pk_XXXXXXXXXXXXXXXXXXXXXXXXX', // ваш Public ID
description: 'Оплата заказа №12345',
amount: 1490.00,
currency: 'RUB',
invoiceId: '12345', // ваш ID заказа
accountId: 'user_789', // ID плательщика в вашей системе
skin: 'classic' // оформление формы
},
{
onSuccess: function (options) { /* показать «успешно» */ },
onFail: function (reason) { /* показать ошибку */ },
onComplete: function (paymentResult) { /* общий финальный коллбек */ }
}
);
});
</script>
- На сервере настройте прием уведомлений (webhooks) и проверку подписи для итогового подтверждения статуса оплаты. Подробности — в CloudPayments API: документация.
Подбор параметров:
| Параметр |
Что это |
Пример |
| publicId |
Ваш публичный идентификатор |
pk_XXXXXXXXXXXXXXXX |
| amount |
Сумма платежа |
1490.00 |
| currency |
Валюта ISO 4217 |
RUB, KZT, USD |
| description |
Описание платежа |
«Оплата подписки» |
| invoiceId |
Номер заказа |
12345 |
| accountId |
Идентификатор покупателя |
user_789 |
Совет: если собираете email/телефон — передавайте их в дополнительных полях, это поможет снизить риск фрода и повысить конверсию 3‑D Secure.
Ссылка на оплату как альтернатива виджету
Если у вас нет возможности внедрять JS или нужны быстрые платежи «по ссылке», используйте «cloudpayments ссылка на оплату». Базовая страница приема платежей: https://c.cloudpayments.ru/payments (часто ищут как «https c cloudpayments ru payments»). Вы формируете URL с параметрами заказа и отдаете клиенту — он перейдет на защищенную форму на стороне CloudPayments.
Этот подход полезен для инвойсов, мессенджеров и email-счетов. При этом вы также можете отслеживать статусы через API и вебхуки. Для массовых рассылок ссылка удобна, но для конверсии в e‑commerce обычно лучше встраиваемый cloudpayments виджет.
Тестирование и отладка
Перед запуском пройдите чек-лист:
- Используйте тестовые ключи и карты из раздела Тестовые карты и демо CloudPayments.
- Проверьте сценарии успеха, отказа и отмены 3‑D Secure.
- Имитация редких статусов и ошибок — по кодам ошибок CloudPayments.
- Сверьте обработку вебхуков и повторные доставки уведомлений при сетевых сбоях.
- Проверьте редиректы Success/Fail, если используете их в настройках.
После успешных тестов переключитесь на боевой Public ID и боевой секретный ключ в серверной части.
Продвинутые возможности: токены, подписки, СБП
- Токенизация карт и «оплата в один клик»: сохраните платежный токен, чтобы списывать без повторного ввода карты (с согласия клиента). Подходит для SaaS, маркетплейсов, подписок.
- Рекуррентные списания: настройте периодические платежи. Для управления подписками пользователям пригодятся материалы найти подписку / отвязать карту и отмена подписки CloudPayments.
- СБП: быстрые платежи через Систему быстрых платежей снижают комиссии и повышают конверсию на мобильных — см. CloudPayments СБП.
- Международные платежи: при необходимости принимайте иностранные карты и валюты — подробнее в разделе Международные платежи CloudPayments.
Если клиент попросит возврат — оформляйте его через кабинет или API, руководство: Возврат денег CloudPayments.
Безопасность, чеки и соответствие 54‑ФЗ
CloudPayments сертифицирован по PCI DSS, а данные карт обрабатываются на стороне провайдера. На вашей стороне:
- Не храните пан-карты и CVV.
- Передавайте только Public ID на клиенте, секретный ключ храните на сервере.
- Формируйте фискальные чеки (54‑ФЗ) — сервис умеет отправлять их автоматически при успешном платеже. Настройки и нюансы — в разделе Чеки и онлайн‑касса CloudPayments.
Прозрачные комиссии и условия смотрите в разделе Тарифы и комиссии CloudPayments.
Уведомления и проверка платежей
- Вебхуки: настройте прием уведомлений об успешных оплатах/возвратах. Подпись сообщений проверяйте по секретному ключу.
- Проверка статуса заказа: для поддержки и бухгалтерии удобно использовать панель или API. Готовые сценарии — в разделе Проверка платежа по заказу.
- Полная схема методов и полей — в CloudPayments API: документация.
Частые ошибки и их решение
- Неверный Public ID: проверьте, что не перепутан тестовый и боевой. Скопируйте заново из кабинета.
- Подпись не сходится: убедитесь, что на сервере используете правильный секретный ключ и алгоритм HMAC.
- CORS/Content Security Policy: добавьте домены CloudPayments для скриптов/фреймов, включая widget.cloudpayments.ru и c.cloudpayments.ru.
- Провалы 3‑D Secure: предложите альтернативный способ (СБП) или повтор платежа; сверяйте коды из раздела Ошибки CloudPayments: коды.
- Возвраты/частичные возвраты: выполняйте согласно инструкции Возврат денег CloudPayments.
Если затруднились — обратитесь в поддержку CloudPayments: контакты и приложите логи запроса/ответа.
Тарифы, плагины и бренд CloudPayments
Для новых пользователей полезно познакомиться с обзором сервиса — что такое CloudPayments.
Итоги и следующий шаг
Виджет CloudPayments — быстрый и безопасный способ принять оплату на сайте. Все, что нужно для старта: Public ID, подключенный скрипт виджета и базовая серверная логика для подтверждения статусов. Если код недоступен, используйте «cloudpayments ссылку на оплату» на https://c.cloudpayments.ru/payments. Далее вы сможете расширять функциональность: токенизация, подписки, СБП, международные платежи и автоматические чеки.
Готовы принять первую оплату? Пройдите быструю настройку по гайду как подключить CloudPayments, а детали по API и тестам — в документации и разделе тестовых карт. Удачных конверсий!
