Интеграция ЮKassa: API, SDK, вебхуки и модули CMS

ЮKassa — это надежный платежный провайдер для интернет-проектов любого масштаба. На этой странице собраны лучшие подходы и практические советы по теме интеграция YooKassa: как выбрать способ подключения (чистое API, SDK или CMS модуль), правильно обрабатывать webhook ЮKassa, настроить кассовые теги 54-ФЗ и вывести проект в продакшн без срывов.

Table of contents

• Варианты интеграции: API, SDK или CMS модуль
• Как работает API ЮKassa
• Аутентификация и безопасность
• SDK ЮKassa: когда использовать
• Webhooks ЮKassa: обработка событий
• Модули CMS ЮKassa
• Кассовые теги 54-ФЗ и чеки
• Пошаговый план внедрения
• Best practices интеграции
• Возвраты и сверка
• Тарифы и методы оплаты
• Отладка и частые ошибки
• Схема интеграции
• Итоги и следующий шаг

Варианты интеграции: API, SDK или CMS модуль

Для старта с ЮKassa доступны три основных пути. Выбор зависит от требований к скорости запуска, кастомизации UX и ресурсов команды.

Способ	Кому подходит	Скорость запуска	Гибкость	Что получите
Чистое API ЮKassa	Middle+/Senior-разработчики, нестандартные сценарии	Средняя	Максимальная	Полный контроль над платежным потоком, UX и логикой
SDK ЮKassa	Команды, желающие ускорить разработку без потери качества	Высокая	Высокая	Готовые классы/методы для работы с платежами, вебхуками, квитанциями
CMS модуль ЮKassa	Интернет-магазины на популярных CMS	Максимальная	Средняя	Быстрый запуск, настройки из админки, минимум кода

Подсказка: если важен Time-to-Market, начните с CMS-модуля или SDK, а в дальнейшем постепенно переходите на API для сложных сценариев.

Как работает API ЮKassa

API ЮKassa позволяет создавать платежи, подтверждать их, делать возвраты и получать статусы в реальном времени. Базовый сценарий:

1. Клиент выбирает способ оплаты на вашем сайте (см. перечень в разделе Платежные методы).
2. Ваш бэкенд дергает метод создания платежа (create payment) через API ЮKassa, передавая сумму, описание, данные покупателя и, при необходимости, параметры подтверждения.
3. Клиент подтверждает оплату (например, 3‑D Secure, открытие банковской страницы, SberPay и др.).
4. ЮKassa отправляет уведомление о результате — через webhook или при запросе статуса.

Ключевые особенности api юкасса:

• Статусы платежа: pending, waiting_for_capture, succeeded, canceled. Для некоторых сценариев требуется отдельный capture (списание) после подтверждения.
• Idempotence-Key: для безопасных повторов запросов используйте уникальный ключ в заголовке каждого критичного запроса (create/capture/refund), чтобы избежать дублей.
• Песочница: тестируйте интеграцию в sandbox до выхода в продакшн.

Подробнее о пользовательском опыте оплаты — на странице Оплата ЮKassa.

Аутентификация и безопасность

Доступ к API осуществляется по HTTPS с использованием HTTP Basic Auth: shopId и secretKey. Обязателен TLS 1.2+. Рекомендуется:

• Ограничить доступ к ключам и хранить их в секрет-менеджере.
• Журналировать все запросы/ответы (без хранения полного PAN и CVV) для последующей сверки.
• Использовать таймауты и повторные попытки с backoff на сетевые ошибки.
• Отдельно про стандарты PCI DSS и безопасную обработку карт — раздел Безопасность и PCI DSS.

SDK ЮKassa: когда использовать

sdk юкасса — короткий путь к стабильной интеграции без глубокого погружения в низкоуровневые детали. Доступны реализации для популярных языков и платформ (например, PHP, Python, Java, Node.js, .NET).

Преимущества SDK:

• Быстрый старт: минимальный шаблон кода для создания/подтверждения платежей и возвратов.
• Единообразная обработка ошибок и статусов.
• Упрощенная работа с вебхуками, идемпотентностью и сериализацией объектов.

Когда выбирают SDK:

• Нужен быстрый запуск с кастомным UX.
• Планируется масштабирование, и важна единая архитектура для нескольких сервисов.

Webhooks ЮKassa: обработка событий

webhook юкасса — основной способ получать изменения статусов асинхронно. Это особенно важно для банковских и альтернативных методов оплаты, где подтверждение может занять время.

Основные события и действия:

Событие	Когда приходит	Что делать
payment.waiting_for_capture	Оплата подтверждена, требуется списание	Вызвать capture, обновить статус заказа на "Ожидает списания"
payment.succeeded	Оплата успешно списана	Перевести заказ в "Оплачен", отдать доступ/отправить товар, сформировать чек
payment.canceled	Оплата отменена/истекла	Освободить резерв, уведомить клиента, предложить альтернативу
refund.succeeded	Возврат завершен	Обновить заказ, уведомить клиента, скорректировать отчетность

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

• Возвращайте 2xx как можно быстрее и обрабатывайте логику асинхронно (очереди, задачи фонового воркера).
• Настройте HTTP Basic Auth для конечной точки вебхуков и используйте трудноподбираемый путь.
• Реализуйте идемпотентную обработку: событие может прийти повторно — проверяйте, не обработано ли оно ранее.
• Ведите аудит-лог: request-id, время, тип события, результат.

Модули CMS ЮKassa

cms модуль юкасса упрощает жизнь интернет-магазинам. Поддерживаются популярные платформы: 1C‑Bitrix, WooCommerce, OpenCart, Magento, PrestaShop, CS‑Cart, MODX и др.

Типовой порядок настройки:

1. Установите официальный модуль из маркетплейса вашей CMS.
2. Введите Shop ID и секретный ключ, включите нужные методы оплаты.
3. Настройте обработку статусов заказов и отправку чеков.
4. Проверьте тестовыми платежами в песочнице.

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

Кассовые теги 54-ФЗ и чеки

Для соответствия 54‑ФЗ важно корректно передавать структуру чека: позиции, ставки НДС, предмет и способ расчета. В ЮKassa это задается в объекте чека; подробнее — на страницах ККТ и 54‑ФЗ и Чеки ЮKassa.

Минимальный набор для позиций:

• Наименование товара/услуги, количество, цена, сумма.
• vat_code — ставка НДС.
• payment_subject — предмет расчета (товар, услуга, агентское вознаграждение и т. п.).
• payment_mode — способ расчета (полная предоплата, частичная оплата и т. д.).
• Контакты покупателя (email и/или телефон) для отправки чека.

Советы:

• Сумма позиций должна сходиться с суммой платежа до копейки.
• Учитывайте доставки/скидки отдельными строками или корректировками.
• Для агентских схем корректно заполняйте данные поставщика.

Пошаговый план внедрения

1. Подключение: оформите договор и получите доступы — см. раздел Подключение.
2. Настройка окружения: заведите sandbox, храните ключи в секрет‑менеджере, подготовьте тестовые данные.
3. Бэкэнд: реализуйте create payment, обработку статусов и, при необходимости, capture.
4. Webhooks: поднимите защищенную конечную точку, включите события, добавьте идемпотентную обработку.
5. Чеки: проброс кассовых тегов 54‑ФЗ, проверка НДС и соответствия сумм.
6. UX: интегрируйте выбранные методы оплаты, учтите особенности SberPay/карты/кошельков — см. Платежные методы.
7. Тестирование: позитивные, негативные и пограничные сценарии; сверка сумм и статусов.
8. Продакшн: переключите ключи, включите логи и алерты, проведите оплату 1–2 реальными чеками малого номинала.

Best practices интеграции

• Идемпотентность: используйте уникальный Idempotence-Key для всех операций списания и возвратов.
• Повторы и таймауты: оборачивайте сетевые вызовы в retry с экспоненциальным backoff, устанавливайте разумные таймауты.
• Валидация: проверяйте валюту, сумму, соответствие заказа и платежа.
• Логирование и трассировка: сохраняйте корреляционные идентификаторы, чтобы разбирать инциденты и делать сверку.
• UX-подсказки: явно сообщайте статус в интерфейсе (обрабатывается, оплачен, отменен), не блокируйте пользователя на долго.
• Безопасность: минимизируйте обработку карточных данных на своей стороне. Подробности — в разделе Безопасность и PCI DSS.

Возвраты и сверка

Возвраты поддерживаются как частичные, так и полные. Запускаются через API или из кабинета. Обработку результата подтверждает событие refund.succeeded во вебхуке.

• Финансы и отчеты: автоматизируйте сверку платежей и возвратов, смотрите раздел Отчеты и сверка.
• Споры и чарджбеки: как действовать при возвратах по инициативе банка — раздел Возвраты и чарджбек.

Тарифы и методы оплаты

Ассортимент методов оплаты влияет на конверсию и UX. Ознакомьтесь с доступными вариантами и настройками в разделе Платежные методы. Если для вас критичны условия эквайринга и SberPay, смотрите Sberbank и ЮKassa и актуальные Тарифы и комиссии.

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

• Дубли платежей: отсутствует или повторно используется Idempotence-Key — делайте ключ уникальным на операцию.
• Несходится сумма: итог по позициям чека не равен сумме платежа — проверьте округления и скидки.
• Вебхук не обрабатывается: нет 2xx ответа или Basic Auth не настроен — проверьте логи сервера и доступность публичного URL.
• Статус заказа не синхронизируется: не обрабатываются события payment.succeeded/canceled — добавьте подписки и обработчики.

Если что-то пошло не так — загляните в раздел Поддержка и troubleshooting и общий FAQ.

Схема интеграции

![Схема интеграции API и вебхуков ЮKassa: клиент — ваш фронтенд — ваш бэкенд — ЮKassa API — вебхуки обратно на ваш бэкенд]

Поток: фронтенд собирает данные заказа, бэкенд создает платеж через API, клиент подтверждает оплату, ЮKassa уведомляет ваш бэкенд через вебхук, вы обновляете заказ и формируете чек.

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

Интеграция Yookassa может быть простой и быстрой с CMS-модулем, или максимально гибкой и масштабируемой через API/SDK. Соблюдайте best practices интеграции, корректно передавайте кассовые теги 54‑ФЗ, подключайте вебхуки и автоматизируйте сверку — так вы получите стабильную оплату и предсказуемую финансовую отчетность.

Готовы начинать? Перейдите к разделу Подключение, выберите оптимальный метод из Платежные методы и запустите первую оплату — подробности на странице Оплата ЮKassa.