Платежи в приложении: подключаем ЮKassa

Допустим, ты собрал приложение или Telegram-бот, и хочешь не просто показывать его друзьям, а брать за него деньги. С этого момента у тебя появляется задача, к которой Claude Code один не справится — нужны юрлицо, документы, договор с платёжной системой. Эта статья — про то как пройти этот путь от начала до конца. Я разберу один способ — ЮKassa, я её сам подключал на одном из своих проектов.

Платёжных систем много: ЮKassa, Робокасса, CloudPayments, Tinkoff, Продамус. Логика везде примерно одинаковая, поэтому если выберешь другую — большую часть статьи можно использовать как карту.

Когда этот раздел нужен, а когда нет

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

Если у тебя 5 знакомых, которые тебе и так переведут — не парься, бери оплату на карту вручную и не трогай эту тему. Подключение требует ИП или ООО, и под 10 продаж в месяц это просто невыгодно.

Что нужно пройти целиком

У всего пути шесть фаз. Первые три — руками, дальше Claude Code снова берёт большую часть работы.

Фаза 1. Подготовка — без этого не подключат

Прежде чем подавать заявку, нужно три вещи: юрлицо, рабочий сайт с ценами, и юридические документы на сайте. Без этого ЮKassa тебя не примет — это требование для всех платёжных систем в России.

Юрлицо

Подойдёт любое из трёх:

• ИП — самый простой вариант. Открывается через Госуслуги или любой банк за 3 рабочих дня. Госпошлина небольшая, через Госуслуги вообще ноль.
• ООО — если у тебя несколько собственников или планы на серьёзный бизнес.
• Самозанятость — тоже можно, но с ограничениями. ЮKassa самозанятых принимает, но способы оплаты сокращены: фактически только СБП и Сберпей, эквайринг по карте напрямую тебе не подключат. Если оборот предсказуемо вырастет — лучше сразу ИП.

После открытия ИП в любом банке тебе откроют расчётный счёт. Банк выбирай любой — Сбер, Точка, Тинькофф, Альфа. У ЮKassa есть нюанс: если расчётный счёт в Сбере, комиссия за приём платежей по картам ниже на 1% — это много в масштабе бизнеса.

Сайт или приложение, где видны цены

Когда ЮKassa получит твою заявку, её сотрудник зайдёт на твой сайт и проверит, что там есть каталог с фиксированными ценами. Не «от 990 ₽», а конкретно: тариф такой-то — 990 ₽ в месяц.

Юридические документы — оферта, политика, возврат

В подвале сайта должны быть три ссылки. Без них тоже не подключат.

• Оферта — публичный договор. Когда человек оплачивает, он автоматически с ним соглашается. В оферте описано что именно ты продаёшь, на каких условиях, как происходит возврат.
• Политика конфиденциальности — как ты хранишь персональные данные. Это требование 152-ФЗ. Если на сайте собирается имя, email, телефон — политика обязательна.
• Условия возврата — обычно дописываются в оферту, отдельной страницы можно не делать.

Сам ничего не пиши — это всё генерирует Claude Code. Открываешь свой проект, в котором собрано приложение, и пишешь:

Я планирую брать оплату за моё приложение. Подскажи какие юридические документы для этого нужны на сайте по российскому законодательству, составь оферту, политику конфиденциальности и условия возврата на основе того что знаешь о проекте. Реквизиты ИП:

— ИНН: XXX
— ОГРНИП: XXX
— Юр. адрес: XXX
— Email для связи: XXX

Размести готовые документы прямо на сайте по адресам /offer, /privacy, /refund и добавь ссылки в подвал.

После того как Claude Code всё сгенерирует — попроси его раскритиковать собственные документы с юридической точки зрения, на корректность ссылок на актуальные статьи закона и на сегодняшнюю дату. Это часто вылавливает мелкие косяки.

Фаза 2. Регистрация в ЮKassa

Это формальный шаг. Заходишь на yookassa.ru, нажимаешь «Подключить», вводишь номер телефона, выбираешь форму юрлица, заполняешь данные о компании — ИНН, ОКВЭД, юридический адрес, цель деятельности. Отправляешь заявку.

Ответ обычно приходит до трёх рабочих дней, но чаще — за несколько часов. Вся переписка идёт через email, с которого ты регистрировался. Реагируют достаточно быстро.

Что могут попросить дополнительно:

• Тестовый доступ к сайту, если цены за авторизацией
• Доработать страницу с тарифами — например, сделать цены крупнее или добавить состав тарифа
• Проверить, что оферта и политика реально открываются по ссылкам в подвале

Любую такую правку делаешь через Claude Code: скриншот письма ЮKassa → в чат → «вот что они просят, сделай». Доработки занимают 10-20 минут.

После проверки в личном кабинете появится договор. Подписываешь либо вживую, либо кодом из СМС. На этом фаза заканчивается — ты официально подключён к ЮKassa.

Фаза 3. Магазин и API-ключи

На каждое отдельное приложение или сайт в ЮKassa создаётся свой магазин. Если у тебя три проекта — будет три магазина. У каждого свой Shop ID и свой Secret Key.

В кабинете нажимаешь «Добавить магазин», вставляешь ссылку на свой сайт или бот, выбираешь категорию бизнеса. Дальше ЮKassa подключает способы оплаты — СБП, Сберпей, банковские карты. На каждый способ может быть отдельная небольшая модерация.

Когда магазин готов, заходишь в раздел «Интеграция → Ключи API». Там два ключа:

• Shop ID — публичный идентификатор магазина
• Secret Key — приватный ключ. Его никому не показывай, это как пин-код от карты

Также можно создать тестовый магазин, в котором всё работает как боевой, но деньги не списываются. Я тестовым не пользовался — тестировал сразу на боевых платежах через промокод 989 ₽ (об этом ниже).

Промпт для Claude Code, чтобы он подготовил место под ключи:

Создай файл .env в корне проекта и добавь туда переменные YOOKASSA_SHOP_ID и YOOKASSA_SECRET_KEY. Убедись, что .env есть в .gitignore. В коде проекта читай ключи только из переменных окружения, не хардкодь.

После этого открываешь файл .env руками и вставляешь свои Shop ID и Secret Key. Сами ключи Claude Code не должен видеть — он не должен их печатать в чат. Если случайно ввёл их в чат — отзови и пересоздай в кабинете ЮKassa.

Фаза 4. Webhook — главная техническая штука

Webhook — это самая важная настройка во всей интеграции. Без него платежи будут проходить, деньги — приходить, а у пользователей — не открываться доступ. И начнётся ад в поддержке.

Что делает Claude Code: пишет на твоём сервере функцию, которая принимает звонок от ЮKassa, проверяет, что это правда от них, и активирует доступ для конкретного пользователя.

Что делаешь ты руками: в кабинете ЮKassa в разделе «Интеграция → HTTP-уведомления» вставляешь ссылку на свой сервер, на которой Claude Code эту функцию развернул. И отмечаешь события, на которые нужны уведомления — главное это payment.succeeded.

Промпт для Claude Code:

Создай интеграцию с ЮKassa для приёма платежей в моём приложении.

Что должно быть:
— Серверная функция-webhook на /api/yookassa-webhook, которая принимает события от ЮKassa
— Главное событие — payment.succeeded (успешная оплата)
— В ответ на webhook возвращай HTTP 200, иначе ЮKassa будет повторять
— ВАЖНО: проверяй, что webhook реально от ЮKassa — фильтруй по их официальным IP-диапазонам, плюс перепроверяй статус платежа через их API. Без этой проверки злоумышленник может прислать фейковый webhook и активировать подписку бесплатно
— Защита от двойной активации: если пользователь уже получил доступ по этому платежу — повторный webhook ничего не делает (идемпотентность)
— Цена платежа берётся из базы данных по тарифу, а не из тела запроса от клиента
— После успешной оплаты — активируй пользователю подписку и отправь уведомление

Используй ключи из .env: YOOKASSA_SHOP_ID и YOOKASSA_SECRET_KEY.

Сначала покажи план и схему данных, потом реализуй.

После того как Claude Code всё развернёт, в кабинете ЮKassa добавляешь URL вебхука и выбираешь события. И только после этого имеет смысл идти в фазу тестирования.

Фаза 5. Подписки и автопродление

Если у тебя разовые покупки (купил курс, оплатил доступ на год) — этой фазы можно не делать. Если у тебя подписочная модель и ты хочешь чтобы деньги списывались сами каждый месяц — придётся отдельно повозиться.

Главное что нужно знать: автопродление в ЮKassa по умолчанию выключено для боевого магазина. Ты сам в кабинете не сможешь его включить — нужно написать менеджеру через форму обратной связи или через email и попросить подключить. Они проверят, что у тебя в интерфейсе:

• Пользователь явно соглашается на автопродление при оформлении подписки
• В настройках есть кнопка «Отвязать карту» или «Отключить автопродление»
• Условия (сумма, период) показаны до оплаты, не задним числом

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

Если у тебя в приложении этого ещё нет — скриним требования ЮKassa, отправляем Claude Code и говорим «добавь вот это в личный кабинет пользователя». Это 20-30 минут работы.

Когда автопродление подключено, на форме оплаты ЮKassa появится чекбокс «Сохранить карту для следующих списаний». Если пользователь его поставил — карта сохраняется на стороне ЮKassa, и ваше приложение получает payment_method_id, через который потом можно списывать без участия пользователя.

Промпт для добавления автопродления:

У меня уже работает разовая оплата подписки через ЮKassa. Хочу, чтобы деньги списывались автоматически каждый месяц.

Реализуй автопродление:
— При первой оплате сохраняй payment_method_id (save_payment_method=true)
— За сутки до конца подписки — попытка автосписания
— Если не получилось — повторить ещё пару раз с паузами (день-два), не блокировать сразу
— Если пользователь отвязал карту — автопродление отключается
— На каждой проблеме с оплатой — уведомление пользователю в email или в бота
— Кнопка «Отключить автопродление» в личном кабинете
— При продлении — сбрось счётчики использования (если у пользователя был лимит на месяц)
— При отключении подписки — лимиты не должны «висеть» в интерфейсе

Не блокируй доступ сразу же после неудачной попытки списания — дай 2-3 дня на решение проблемы (карта могла протухнуть, деньги пришли позже). Это называется grace period.

Фаза 6. Тестирование на 1 рубль

Когда всё развернуто и вебхук в кабинете прописан — тестируй. Можно через тестовый магазин (там игрушечные деньги), а можно лайфхаком, как делал я: тестируешь на боевом, но за 1 рубль.

Что проверить во время тестирования:

• Открывается виджет оплаты ЮKassa, в нём корректные сумма и название тарифа
• Деньги реально списываются с карты
• В течение 3-5 секунд после оплаты у пользователя в приложении открывается доступ
• Если деньги списались, а доступ не открылся за 20 секунд — что-то с вебхуком, скриним и отправляем Claude Code на разбор
• Кнопка «Отвязать карту» работает: после нажатия в кабинете ЮKassa автопродление отменяется
• При отмене подписки доступ остаётся до конца оплаченного периода (это правильное поведение, деньги за месяц вперёд не возвращаются)
• Всё работает с мобильной версии — открывается, виджет помещается, оплата проходит

Если что-то не работает — не начинай гадать. Скриншот ошибки → в Claude Code → «вот что у меня не работает, проверь по логам почему, напиши план починки и сделай». Это рабочий шаблон для всей этой темы: все ошибки разбираются скриншотами.

Подводные камни — что у меня не получилось с первого раза

Шесть неочевидных штук, на которые я сам напоролся.

1. Перепутал ID магазинов

У меня в ЮKassa было три магазина для разных проектов. При настройке вебхука я случайно вставил Shop ID не того проекта. В итоге пользователь оплачивает приложение А, а уведомление приходит в приложение Б. Деньги вроде ушли, доступ не открылся.

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

2. CSP блокирует виджет

Виджет оплаты ЮKassa — это JavaScript на их стороне, который встраивается в твою страницу. Если у тебя на сайте настроена политика CSP (Content Security Policy), то браузер может заблокировать загрузку их скрипта. Проявляется тем, что нажимаешь «Оплатить», а ничего не происходит — в консоли красная ошибка.

Решение: в Claude Code → «у меня виджет ЮKassa не открывается, в консоли ошибка CSP, разберись и почини». Он добавит нужные домены ЮKassa в whitelist.

3. Платёж не создаётся

Это часто ошибка в данных запроса. Не та сумма, не то описание, не тот формат. ЮKassa в ответе пишет конкретно что не так — это сообщение нужно скриншотом отправить Claude Code, он разберёт.

4. Подписка зависает в статусе ожидания

Деньги списались, статус платежа в ЮKassa успешный, но в твоём приложении пользователь по-прежнему «гость». Это всегда вебхук — либо не настроен, либо не отвечает HTTP 200, либо упал из-за ошибки.

Решение: открываешь логи сервера, смотришь приходил ли запрос. Если приходил, но упал — Claude Code покажет почему. Если не приходил — проверяешь URL в кабинете ЮKassa. И отдельно стоит сделать фоновую задачу (cron), которая раз в час сверяет платежи через API ЮKassa со своей базой и активирует пропущенные. Тогда даже если вебхук однажды не доедет — пользователь не останется без доступа.

5. Хранение персональных данных не на российском сервере

Если ты хранишь данные пользователей в Supabase, Firebase или другом сервисе с серверами вне России — формально это нарушение 152-ФЗ. Закон требует, чтобы первичная обработка персональных данных российских граждан шла на российских серверах.

На уровне «у меня 50 пользователей и я не работаю с госконтрактами» это редко становится проблемой. Но если планируешь вырасти и работать всерьёз — нужно перенести данные на российский хостинг (Selectel, Yandex Cloud, VK Cloud) или хотя бы держать в России дублирующую базу. Это отдельный пласт работы, выходящий за рамки этой статьи.

Минимум, что точно стоит сделать сразу: проконсультироваться с юристом и не хранить лишнее. Не записывай в базу то, что тебе не нужно для работы продукта.

6. Не сразу подключил рекуррентные

Я сначала запустил подписочное приложение без автосписания и две недели прожил с ситуацией, когда пользователи должны были вручную каждый месяц нажимать «продлить». Не нажимали. Потом доработал, дописал в ЮKassa, доделал отвязку карты — после этого retention сразу подскочил.

Если делаешь подписку — закладывай автопродление сразу, не откладывай. Доработать постфактум стоит дороже чем сделать с первого раза.

Чек-лист перед запуском

Когда всё готово — пройдись по этому списку. Каждый пункт — реальная ошибка, которая стоила денег или нервов пользователей у тех, кто это уже проходил. Скриншот этого чек-листа можно отправить Claude Code и попросить его проверить твой проект по нему.

• Webhook отвечает HTTP 200 на каждое событие
• Повторный webhook от ЮKassa не активирует подписку дважды (идемпотентность)
• Цена тарифа берётся из базы данных, а не из тела запроса клиента
• Webhook фильтрует запросы по IP ЮKassa или проверяет статус платежа через API
• При продлении подписки счётчики использования сбрасываются
• При отключении подписки доступ заканчивается ровно по концу оплаченного периода, а не сразу
• Бесплатный план не теряется после покупки подписки и обратно
• Неудачное автосписание не блокирует мгновенно — есть grace period 2-3 дня
• Пользователь получает уведомление о любой проблеме с оплатой
• Промокод не перезаписывает более выгодный тариф
• Возврат денег отзывает и бонусы, начисленные с этой оплаты
• Есть фоновая cron-задача, которая раз в час сверяет платежи и активирует пропущенные
• На сайте есть оферта, политика конфиденциальности, условия возврата — все три ссылки рабочие в подвале
• Кнопка «Отвязать карту» работает и реально удаляет payment_method_id
• Виджет оплаты открывается с мобильной версии
• Ключи ЮKassa лежат в .env, .env есть в .gitignore

Что важно понять про всё это

Я подключал платёжный модуль примерно два дня. Не два полных дня, а после основной работы по 2-3 часа вечером — настраивал, переписывался с поддержкой, ловил баги. Если бы это пришлось делать с нуля без Claude Code и без чьего-то опыта — было бы дольше в разы.

Главное правило: не усложняй. Когда что-то не работает, не пытайся разобраться в технических терминах сам. Скриншот → в Claude Code → «я не понимаю что это, объясни как новичку и почини». Это работает для CSP, для редиректов, для ошибок API — для всего.

И вторая штука: не бойся писать в ЮKassa. У них нормальная поддержка, отвечают за часы, не за дни. Если что-то не получается на их стороне — пиши на почту, не сиди молча.