Обновлено: октябрь 2026
Если собираете продукт в России и принимаете деньги от физлиц — ЮKassa один из самых очевидных выборов. Комиссия по СБП от 0,4%, карты от 2,8%, подключение бесплатное. Готовая интеграция при нормальном стеке делается за день: утром подаете документы, вечером проводите первый тестовый платеж.
В этом гайде — весь путь от регистрации до первого реального платежа. Разберем, как получить shopId и secretKey, настроить webhook и не наступить на классические грабли вроде CSRF и пересчета комиссии.
TL;DR: ЮKassa подключается в три шага: регистрация + договор (1–3 рабочих дня), тестовый магазин с API-ключами, настройка webhook. Комиссия за карты от 2,8%, СБП от 0,4%. С 1 января 2026 года к комиссии добавляется НДС 22% от суммы комиссии. Боевая интеграция отличается от тестовой только заменой ключей.
Шаг 1. Кто может подключить ЮKassa?
ЮKassa работает с ИП, ООО и самозанятыми. Для самозанятых — упрощенная схема, но есть потолок по доходу.
ЮKassa доступна для трех форм бизнеса: юрлицо (ООО), индивидуальный предприниматель и самозанятый. Выбор влияет на набор документов при заполнении анкеты.
Самозанятые подключаются проще всего — меньше документов, нет требований к бухгалтерии. Ограничение одно: годовой доход не может превышать 2,4 млн рублей. Если оборот больше — только ИП или ООО.
Важный момент для подрядчиков: если вы разработчик, которому заказчик сказал «подключи нам ЮKassa», регистрироваться должен сам заказчик. Потом он просто добавляет вас в личный кабинет как разработчика. Попытка зарегистрироваться на свои данные за чужой бизнес — это путь в никуда.

Шаг 2. Как зарегистрироваться в ЮKassa?
Регистрация занимает 10–15 минут, но до реальных платежей пройдет 1–3 рабочих дня на проверку анкеты.
Переходите на yookassa.ru и жмете «Подключить». Порядок такой:
- Телефон + SMS-код.
- Пароль и email для уведомлений.
- Форма бизнеса — ИП, ООО или самозанятый.
- ИНН или название компании.
После этого попадаете в личный кабинет. На главной странице появится чеклист шагов для подключения.
Первым делом — заполнить анкету и заключить договор. Переходите в раздел «Данные договора» и указываете:
- реквизиты расчетного счета (на него будут приходить деньги с продаж),
- данные о государственной регистрации (ФНС часто предзаполняет их автоматически — проверьте),
- паспорт руководителя или ИП (фото без бликов, не обрезанное),
- для ООО — данные бенефициарных владельцев, то есть физлиц с долей больше 25%.
Последний пункт обязателен по закону и часто становится неожиданностью для новичков. Пропустить нельзя.
После отправки анкеты ждете проверки. Ответ приходит на email, в среднем это 3 рабочих дня. Но и тут есть лайфхак: пока идет проверка, уже можно начинать техническую интеграцию через тестовый магазин.
Договор подписывают онлайн или скан-копией — выбирайте онлайн, это экономит время.
Шаг 3. Где взять shopId и secretKey?
ShopId — в разделе «Операции», секретный ключ — в разделе «Интеграция» -> «Ключи API». Для теста нужен ключ с префиксом test_.
Это два параметра, без которых не обходится ни одна интеграция с платежными системами. Оба находятся в личном кабинете.
shopId — номер вашего магазина в системе ЮKassa. Отображается напротив названия магазина в разделе «Операции».
Секретный ключ — в разделе «Интеграция» -> «Ключи API». Тестовый ключ начинается с test_, боевой — без этого префикса.
Создать тестовый магазин можно сразу после регистрации: раздел «Интеграция» -> «Настройки интеграции», жмете «Добавить тестовый магазин». Через минуту появится отдельный shopId и тестовый ключ. В тестовом режиме деньги не списываются — все операции симулируются.
Базовая инициализация клиента выглядит одинаково на любом языке. Вот Python-пример из официального SDK:
from yookassa import Configuration
# Тест
Configuration.configure('ВАШ_SHOP_ID', 'test_XXXXXXXXXX')
# Бой — меняете только ключ
Configuration.configure('ВАШ_SHOP_ID', 'live_XXXXXXXXXX')Node.js и PHP — та же логика: передаете shopId и secretKey при инициализации клиента. Весь остальной код не меняется при переключении с теста на бой.
Шаг 4. Как создать платеж через API ЮKassa?
Создание платежа — POST-запрос к api.yookassa.ru/v3/payments. В ответ получаете ссылку, на которую перенаправляете пользователя.

Логика проведения оплаты простая: вы создаете платеж на стороне ЮKassa, получаете ссылку, перенаправляете пользователя. Он платит, ЮKassa уведомляет ваш сервер через webhook.
Пример curl-запроса из официальной документации ЮKassa (yookassa.ru/developers):
curl https://api.yookassa.ru/v3/payments \
-X POST \
-u <Shop ID>:<Secret Key> \
-H 'Idempotence-Key: <Уникальный ключ>' \
-H 'Content-Type: application/json' \
-d '{
"amount": {
"value": "1000.00",
"currency": "RUB"
},
"capture": true,
"confirmation": {
"type": "redirect",
"return_url": "https://ваш-сайт.ru/success"
},
"description": "Заказ №123"
}'В ответ приходит объект платежа с полем confirmation.confirmation_url — это и есть ссылка для пользователя.
Есть нюанс, о котором часто не думают на старте: никогда не делайте запрос к ЮKassa напрямую с фронтенда. Если создавать платеж из браузера, сумму легко подделать — вместо 1000 рублей клиент заплатит 10. Запрос должен идти через бэкенд, который сам получает правильную цену из базы данных.
| Параметр | Описание |
|---|---|
| amount.value | Сумма в рублях строкой с двумя знаками после точки |
| capture | true — одностадийная оплата, false — двухстадийная (сначала холд) |
| confirmation.return_url | Куда перенаправить пользователя после оплаты |
| description | Текст, который увидит покупатель на странице оплаты |
| Idempotence-Key | Уникальный ключ запроса — защита от дублирования платежа |
Шаг 5. Как настроить webhook для получения уведомлений?
Webhook — URL на вашем сервере, куда ЮKassa отправляет POST-запрос при изменении статуса платежа. Обязателен HTTPS.
Это самый важный шаг, который часто делают небрежно. Без webhook вы не узнаете, что пользователь оплатил — придется каждые несколько секунд дергать API вопросом «ну как там платеж?». Это и медленно, и неэффективно.
Настройка в личном кабинете: «Интеграция» -> «HTTP-уведомления» -> указываете URL. Формат: https://ваш-сайт.ru/webhook/yukassa.
Два ключевых события, на которые подписываетесь:
payment.succeeded— платеж прошел, деньги списаныpayment.canceled— платеж отменен или истекло время
Пример простого обработчика на Python/Django:
import json
from django.http import HttpResponse
from yookassa.domain.notification import (
WebhookNotificationEventType,
WebhookNotificationFactory
)
from yookassa.domain.common import SecurityHelper
def yukassa_webhook(request):
# Проверяем IP — ЮKassa присылает с известных адресов
ip = request.META.get('REMOTE_ADDR')
if not SecurityHelper().is_ip_trusted(ip):
return HttpResponse(status=400)
event_json = json.loads(request.body)
notification = WebhookNotificationFactory().create(event_json)
if notification.event == WebhookNotificationEventType.PAYMENT_SUCCEEDED:
payment = notification.object
order_id = payment.metadata.get('order_id')
# Обновляем статус заказа в базе
update_order_status(order_id, 'paid')
return HttpResponse(status=200)Webhook должен отвечать кодом 200 OK. Любой другой код — и ЮKassa будет повторять запросы в течение 24 часов.
Есть нюанс с Django (и Flask тоже): если используете CSRF-защиту, webhook-обработчик нужно выводить из-под нее через декоратор @csrf_exempt. Это осознанное решение — ЮKassa не передает CSRF-токен. Для компенсации проверяйте IP из белого списка ЮKassa через SecurityHelper().is_ip_trusted(ip).
Шаг 6. Как пересчитать сумму с учетом комиссии?
ЮKassa снимает комиссию из суммы платежа, а не добавляет сверху. Если хотите получить ровно 1000 рублей, нужно выставить счет на большую сумму.
Это один из самых частых источников путаницы при первой интеграции с платежными системами. ЮKassa не «добавляет» комиссию к платежу — она вычитает ее из той суммы, которую вы выставляете.

Пример для тарифа 3% по картам: если хотите получить 1000 рублей, клиент должен заплатить примерно 1030 рублей. Формула:
сумма для клиента = нужная сумма / (1 - комиссия)С 1 января 2026 года к комиссии добавляется НДС 22% от суммы комиссии. То есть реальный вычет стал немного больше.
На практике есть два подхода. Первый — включить комиссию в расходы и выставлять цену без пересчета. Второй — явно добавлять комиссию к стоимости (тогда нужно знать тариф заранее, а ЮKassa не дает получить его в реальном времени через API). Для большинства небольших проектов первый вариант проще.
Тарифы и комиссии ЮKassa в 2026 году
Базовые ставки: карты от 2,8%, СБП от 0,4%. Итоговый тариф зависит от оборота и категории бизнеса.
ЮKassa — платежный сервис от Яндекса. Комиссия по картам стартует от 2,8%, СБП от 0,4%. Подключение бесплатное, абонентской платы нет. При обороте от 1 млн рублей в месяц доступны индивидуальные условия.
| Способ оплаты | Базовая комиссия | Примечание |
|---|---|---|
| Карты (Visa, MC, МИР) | от 2,8% | Зависит от категории бизнеса |
| СБП | от 0,4% | Самый выгодный вариант |
| SberPay | от 2,8% | Оплата через Сбер Онлайн |
| T-Pay | от 3,8% | Оплата через Т-Банк |
| ЮMoney | от 2,8% | Электронный кошелек |
Важное изменение 2026 года: с 1 января 2026 года НДС вычитается вместе с комиссией — 22% от суммы комиссии. Вычет НДС зависит от способа оплаты.
Чтобы получить сниженную комиссию, при подключении выбирайте сервис «Чеки от ЮKassa» — это встроенное решение для отправки чеков по 54-ФЗ, которое одновременно снижает ставку.
СБП — отдельная история. Подключить прием платежей через СБП можно только вместе с другими способами ЮKassa: банковскими картами, кошельком ЮMoney, SberPay. Зачисление на расчетный счет — в любом российском банке, подключение от одного рабочего дня.
Как протестировать интеграцию с ЮKassa?
Тестовый магазин с ключами test_ позволяет проводить платежи без списания реальных денег. Тестовые карты — в документации ЮKassa.
После создания тестового магазина в личном кабинете используйте тестовые карты из официальной документации ЮKassa (yookassa.ru/developers). Стандартный набор для теста:
- Успешная оплата: номер карты 5555 5555 5555 4444, срок 12/26, CVV 000
- Отклоненная оплата: 5555 5555 5555 4477
При тестировании webhook на локальной машине возникает проблема: ЮKassa не может достучаться до localhost. Решение — ngrok. Он создает временный HTTPS-адрес, который туннелирует запросы на ваш локальный сервер:
ngrok http 8000
# Получаете: https://abc123.ngrok.io
# Этот адрес вставляете в поле webhook в личном кабинете ЮKassaПроверить, что webhook работает: провести тестовый платеж и убедиться, что в консоли сервера появился POST-запрос от ЮKassa с JSON-телом уведомления.
После успешного теста переход на боевой режим — только замена ключей. Код не трогаете.
Готовые модули vs API — что выбрать?
Готовые модули для WordPress, Tilda, 1С — быстрее на 80%. Прямая интеграция через API — гибче, нужна при нестандартной логике.
В ЮKassa есть готовые модули для самых популярных систем: Tilda, Wix, AmoCRM, WordPress и других. Для каждой системы есть инструкция и документация.
Когда выбирать модуль: вы на стандартной CMS, нет нестандартной бизнес-логики, хотите запустить прием платежей за день без написания кода.
Когда нужна прямая интеграция через API: у вас своя платформа, кастомный флоу оплаты (например, двухстадийный: сначала холд, подтверждение после выполнения услуги), нужно передавать metadata для связи платежа с заказом, или строите мобильное приложение.

| Параметр | Готовый модуль | API |
|---|---|---|
| Скорость запуска | Часы | День-два |
| Гибкость | Низкая | Высокая |
| Нужен разработчик | Нет | Да |
| Кастомный флоу | Нет | Да |
| Metadata в платеже | Ограничено | Да |
Максим Наговицын: «Когда делали GoBanana — веб-версию собрали за 3 часа после выхода модели. Платежи подключили через API, потому что нужна была своя логика: холд при создании заказа, подтверждение после генерации. Готовый модуль тут не справился бы. Но если бы это был просто лендинг с одним продуктом — взяли бы модуль для Tilda и закрыли вопрос за 20 минут.»
Двухстадийная оплата — когда и зачем?
Двухстадийная схема: сначала деньги блокируются на карте (холд), потом вы их подтверждаете или отменяете. Удобно для услуг с отложенным выполнением.
Это особенность, которая отличает ЮKassa от многих конкурентов. При создании платежа с capture: falseденьги блокируются, но не списываются. Пока транзакция в статусе waiting_for_capture, вы можете:
- подтвердить платеж (деньги спишутся окончательно),
- отменить его (деньги вернутся клиенту без комиссии).
Классический кейс: заказ такси. Клиент оплатил, такси не приехало — просто отменяете транзакцию, деньги возвращаются без бюрократии.
Или сервис с моделированием: клиент оплачивает генерацию, если она упала с ошибкой — отменяете холд автоматически. Логика опроса вебхука при этом не меняется — просто вместо capture: true отправляете запрос на подтверждение после выполнения задачи.
Ошибки, которые тормозят при интеграции ЮKassa
Три самых частых проблемы: CSRF на webhook, забыли указать HTTPS, неправильный расчет суммы.
Ошибка 1: CSRF блокирует webhook
Django и Flask по умолчанию проверяют CSRF-токен на POST-запросах. ЮKassa его не присылает, поэтому webhook падает с ошибкой 403 Forbidden. Решение — декоратор @csrf_exempt на обработчике. Компенсируете это проверкой IP: ЮKassa шлет уведомления с фиксированного диапазона адресов, их можно проверить через SecurityHelper().is_ip_trusted(ip).
Ошибка 2: webhook на HTTP
ЮKassa требует HTTPS для доставки уведомлений. Если указали http:// вместо https:// — уведомления не придут. На проде это обычно закрыто автоматически, а для локального тестирования нужен ngrok.
Ошибка 3: не сохранили payment_id
При создании платежа ЮKassa возвращает уникальный id платежа. Его нужно сохранить в базе рядом с заказом. Когда придет webhook с уведомлением об успехе — вы свяжете его с конкретным заказом по этому id. Без этого непонятно, что именно оплатили.

Часто задаваемые вопросы
Сколько стоит подключить ЮKassa? Подключение бесплатное. Комиссия берется только за успешно проведенные платежи: карты от 2,8%, СБП от 0,4%. Абонентской платы нет.
Можно ли подключить ЮKassa как самозанятый? Да. Самозанятые подключаются по упрощенной схеме. Ограничение — годовой доход не более 2,4 млн рублей. Чеки формируются автоматически.
Что такое webhook в ЮKassa и зачем он нужен? Webhook — это URL на вашем сервере, на который ЮKassa отправляет уведомление, когда платеж прошел или отклонен. Без него вы не узнаете об успешной оплате без постоянных запросов к API.
Где взять shopId и secretKey для ЮKassa? ShopId отображается напротив названия магазина в разделе «Операции». Секретный ключ — в разделе «Интеграция» -> «Ключи API». Для теста нужен ключ с префиксом test_.
Нужен ли HTTPS для интеграции ЮKassa? HTTPS обязателен для webhook-уведомлений — ЮKassa не отправит POST-запрос на HTTP-адрес. Для тестирования на локальной машине используют ngrok, который создает временный HTTPS-адрес.
Как ЮKassa не включает комиссию — надо пересчитывать сумму? Именно. ЮKassa списывает комиссию из суммы платежа. Если хотите получить 100 рублей, нужно выставить счет на 102-103 рубля в зависимости от тарифа. Или просто принять это в расходы.
Сколько времени занимает проверка анкеты ЮKassa? В среднем 3 рабочих дня, но нередко быстрее. Пока ждете, можно начинать техническую интеграцию через тестовый магазин.
Что дальше
Интеграция с платежными системами — один из базовых навыков при создании любого коммерческого продукта. ЮKassa закрывает российский рынок, и логика работы схожа с другими эквайрингами — разобравшись здесь, подключить, например, Тинькофф Бизнес будет намного проще.
Если строите что-то на Next.js или другом современном стеке, посмотрите каталог AI-инструментов — там есть обзоры инструментов, которые помогут ускорить разработку. А если нужна помощь с архитектурой или выбором стека для вашего проекта, запишитесь на консультацию к Максиму.
Данные по тарифам актуальны на июнь 2026. Источники: yookassa.ru/fees, yookassa.ru/developers. Перед подключением уточняйте условия в личном кабинете ЮKassa — тарифы могут зависеть от категории бизнеса и оборота.
Обновлено: октябрь 2026 — команда VibeCoderz