CloudPayments
Войти

Интеграция сайта и CMS с ЮKassa: ключи, вебхуки и тестирование

Получить CloudPayments бесплатно

Интеграция сайта и CMS с ЮKassa: ключи, вебхуки и тестирование

Зачем нужна интеграция ЮKassa

Интеграция ЮKassa (ю касса) позволяет принимать онлайн‑платежи банковскими картами, СБП, электронными кошельками и другими методами прямо на вашем сайте, в мобильном приложении или CMS. Правильно настроенные ключи, вебхуки и API обеспечивают стабильный прием платежей, корректное отображение статусов и автоматическую синхронизацию с вашим бэкендом и отчетностью.

Если вы только начинаете, зарегистрируйте аккаунт и выполните вход в Личный кабинет. Новым мерчантам поможет страница Регистрация, а при проблемах входа — разделы Вход и Ошибки входа. Восстановить доступ можно через Восстановить доступ.

Схема работы: от клиента до платежа

![Схема интеграции ЮKassa — последовательность шагов клиента, сайта, API и вебхуков]

Коротко о потоке:

Получить CloudPayments бесплатно
  1. Клиент выбирает товар и жмет «Оплатить».
  2. Ваш сайт/магазин создает платеж через API ЮKassa (иногда это делает установленный плагин CMS).
  3. Пользователь оплачивает на защищенной платежной странице.
  4. ЮKassa отправляет вебхук о статусе платежа на ваш endpoint.
  5. Вы подтверждаете оплату, отгружаете товар и формируете отчетность.

Ключи ЮKassa и учетные данные

Для безопасной интеграции вам потребуются несколько типов ключей/идентификаторов. Они различаются по назначению — от доступа к API до проверки подписи уведомлений.

Тип ключа/идентификатора Где получить Где используется
Shop ID (идентификатор магазина) Личный кабинет В Basic-авторизации запросов к API
Secret Key (секретный ключ) Личный кабинет Подпись/авторизация API-запросов, валидация уведомлений в ряде сценариев
Секрет вебхука (подпись) При создании webhook в ЛК Проверка подлинности уведомлений от ЮKassa
OAuth-токен (опционально) По расширенным сценариям Интеграции с партнерскими решениями, требующими OAuth

Где получить ключи

  • Зайдите в Личный кабинет под своей учетной записью. Если еще нет аккаунта — пройдите Регистрацию.
  • Перейдите в раздел настроек интеграции и сгенерируйте Secret Key. Скопируйте его в конфигурацию бэкенда/плагина.
  • Создайте вебхук и зафиксируйте «секрет для уведомлений» — он нужен для проверки подписи сообщений.

Как хранить и кто должен иметь доступ

  • Храните ключи в переменных окружения или менеджерах секретов (не в репозитории).
  • Раздавайте доступ только администраторам, соблюдайте политику наименьших привилегий. Подробнее — в разделе Безопасность.

Вебхуки ЮKassa: настройка и проверка подписи

Вебхуки ЮKassa уведомляют ваш сервис о смене статуса платежа. Это важно, потому что клиент может закрыть браузер сразу после оплаты, а ваш сервер все равно получит финальный статус.

Ключевые события:

Событие Назначение
payment.waiting_for_capture Платеж авторизован и ожидает подтверждения с вашей стороны
payment.succeeded Платеж успешно завершен, можно отгружать товар
payment.canceled Платеж отменен
refund.succeeded Возврат успешно проведен

Рекомендации по настройке вебхуков:

  • Создайте HTTPS endpoint, доступный из интернета (например, /api/yookassa/webhook).
  • Включите логирование запросов и ответов вебхука (без сохранения персональных данных).
  • Верифицируйте подпись: вычисляйте HMAC по телу запроса и сравнивайте с подписью из заголовков/настроек, используя «секрет для уведомлений».
  • Возвращайте HTTP 200 в случае корректной обработки, иначе ЮKassa может повторять доставку уведомления.

API ЮKassa: основные запросы

Интеграция через API ЮKassa (api юкасса) строится вокруг операций с платежами и возвратами. Ниже — базовые действия.

  • Создать платеж: POST /payments
  • Получить платеж: GET /payments/{payment_id}
  • Подтвердить (capture) платеж: POST /payments/{payment_id}/capture
  • Отменить платеж: POST /payments/{payment_id}/cancel
  • Создать возврат: POST /refunds

Советы по реализации:

  • Авторизация: используйте Basic Auth со связкой Shop ID + Secret Key.
  • Идемпотентность: в запросах на создание платежа и возврата передавайте заголовок Idempotence-Key (уникальный UUID на операцию), чтобы избежать дублей при повторных попытках.
  • Валюта и суммы: работайте в рублях и корректно округляйте суммы до двух знаков.
  • Таймауты и повторы: закладывайте повтор запросов и обработку сетевых ошибок.

Минимальный пример JSON-тела создания платежа (сокращенный):

{
  "amount": { "value": "100.00", "currency": "RUB" },
  "capture": true,
  "confirmation": { "type": "redirect", "return_url": "https://example.ru/return" },
  "description": "Заказ №1001"
}

Отслеживать статусы, сверять оплаты и формировать выгрузки удобно через раздел Платежи и отчеты.

Плагины CMS ЮKassa: WordPress, 1C‑Битрикс, OpenCart и др.

Если вы используете CMS/CMF, готовые плагины ЮKassa ускоряют запуск.

Популярные платформы:

  • 1C‑Битрикс, Битрикс24
  • WordPress + WooCommerce
  • OpenCart
  • CS‑Cart
  • PrestaShop
  • MODX
  • Drupal

Общий порядок установки плагина (может незначительно отличаться):

  1. Установите модуль через маркетплейс вашей CMS или скачайте дистрибутив.
  2. Активируйте модуль и перейдите в его настройки.
  3. Укажите Shop ID, Secret Key, включите тестовый режим при необходимости.
  4. Задайте URL для вебхуков (если модуль не делает это автоматически).
  5. Настройте способы оплаты (карты, СБП, кошельки и др.).
  6. Проведите тестовый платеж и проверьте корректность статусов заказов в админке.

Плагины CMS ЮKassa обычно уже умеют:

  • Создавать платежи и обрабатывать ответы API;
  • Подписывать и валидировать уведомления (вебхуки ю касса);
  • Сопоставлять статусы «Оплачен», «Ожидает оплаты», «Отменен».

Тестовый режим и чек-лист перед запуском

Тестирование критично, чтобы в продакшене не возникли незапланированные отказы. Включите тестовый режим в Личном кабинете и выполните следующие проверки:

  • Проверьте успешный платеж и отмену.
  • Проверьте сценарий waiting_for_capture, если у вас двухстадийная схема (auth+capture).
  • Оформите частичный возврат и убедитесь, что статус в CMS и вашей CRM корректно обновился.
  • Смоделируйте повторную доставку вебхука: ваш endpoint должен быть идемпотентным и обрабатывать дубликаты безопасно.
  • Проверьте корректный редирект на return_url после успешной оплаты и корректное отображение страницы заказа.
  • Убедитесь, что бухгалтерская и аналитическая отчетность сходится, а комиссии учтены согласно Тарифы и комиссии.

Совет: используйте тестовые карты из официальной документации и зафиксируйте все кейсы в чек-листе — это упростит дальнейшую регрессию.

Безопасность: лучшие практики

Интеграция платежей — зона повышенной ответственности. Следуйте рекомендациям:

  • Обновляйте плагины и SDK, используйте LTS-версии языка/фреймворка.
  • Храните ключи и секреты только на серверной стороне. Не выкладывайте их в Git или клиентский JavaScript.
  • Подтверждайте все входящие вебхуки по подписи, проверяйте содержание событий и соответствие суммы/заказа.
  • Шифруйте трафик (HTTPS), используйте современные шифросuites и HSTS.
  • Ограничьте доступ к админке CMS и Личному кабинету, включите MFA. Подробнее — в разделе Безопасность.
  • Для мобильных приложений используйте нативные SDK и прокси-сервер для операций, требующих секретов. См. раздел Мобильная интеграция.

Отладка и типичные ошибки

Ниже — частые ситуации при интеграции с api юкасса и способы их решения.

Симптом Возможная причина Что проверить
HTTP 401/403 при обращении к API Неверный Shop ID или Secret Key Синхронизируйте ключи из ЛК, проверьте формат Basic Auth
HTTP 400/422 при создании платежа Некорректные поля запроса Валюта, формат суммы, уникальный Idempotence-Key
Вебхуки не приходят Неверный URL или SSL-проблемы Доступность endpoint из интернета, срок действия сертификата
Несовпадение суммы/статуса Ошибка бизнес-логики в обработчике Идемпотентность хэндлера, валидация подписи вебхука
Дубли платежей Повтор запроса без Idempotence-Key Генерируйте уникальный ключ для каждой операции

Если проблема связана с доступом к аккаунту — проверьте Ошибки входа или Восстановить доступ. По техническим вопросам и эскалации обращайтесь в Поддержку.

Для сверки транзакций и актов используйте материалы в разделе Платежи и отчеты.

FAQ по интеграции ЮKassa

  • Можно ли запустить без разработчика? Да, с CMS это реально: установите официальный модуль, укажите ключи и пройдите тестовые платежи.
  • Сколько занимает подключение? От 30 минут (CMS) до 1–2 дней для кастомного бэкенда с вебхуками и проверкой подписи.
  • Что выбрать: одностадийную или двухстадийную оплату? Если вы отгружаете не сразу, двухстадийная схема (authorize + capture) безопаснее для возвратов и частичных списаний.
  • Как учитывать комиссии? Сверяйте информацию в Тарифы и комиссии и автоматизируйте выгрузки через Платежи и отчеты.

Итоги и следующий шаг

Интеграция с ЮKassa — это понятная последовательность: получить ключи, подключить API или плагин CMS, настроить вебхуки, протестировать сценарии и соблюсти требования безопасности. Следуйте этому руководству, и вы быстро начнете принимать платежи без лишних рисков и потерь.

Готовы к запуску? Зайдите в Личный кабинет, проверьте настройки, выполните контрольные тесты и при необходимости напишите в Поддержку. Удачных продаж!

Получить CloudPayments бесплатно