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

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

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

Table of contents

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Минимальный пример 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 ускоряют запуск.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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