Курс

ЮKassa: платежка для России

МОДУЛЬ 7: ПРИЁМ ОПЛАТ • Урок 4 из 6

ЮKassa это бывшая Яндекс.Касса. Не знаю как щас, но раньше это был хороший и удобный сервис, который прекрасно решал мои задачи.

[ ПОЧЕМУ ЮKASSA ]

ЮKassa это официальная российская платежная система от Яндекса. Когда можно её использовать:

  • У тебя есть ИП или ООО
  • Работаешь с российской аудиторией
  • Нужны платежи СБП (Система Быстрых Платежей)

[+] Плюсы:

  • СБП — клиент платит через мобильный банк, без комиссии (переводы моментальные)
  • Поддержка всех российских карт
  • Официальная система с поддержкой и документацией на русском
  • Готовые SDK для разных языков (PHP, Python, JavaScript)
  • Низкие комиссии

[-] Минусы:

  • Требует регистрации ИП/ООО (не подходит для физических лиц)
  • Нужна модерация (проверка документов занимает 1-3 дня)
  • Есть список запрещённых товаров и услуг (как у любой платежной системы)

[ ШАГ 1: РЕГИСТРАЦИЯ ]

Требования:

  • ИП или ООО
  • ОГРН/ОГРНИП, ИНН
  • Банковский счет на юрлицо
  • Документы подтверждающие вид деятельности

Как зарегистрироваться:

  1. Открой yookassa.ru
  2. Нажми "Подключить магазин"
  3. Заполни форму:
    • Название организации
    • ИНН
    • ОГРН/ОГРНИП
    • Контактные данные
  4. Подтверди email
  5. Дождись звонка менеджера (обычно звонят на следующий день)

Модерация:

ЮKassa проверит твои документы (1-3 дня):

  • Проверят документы организации
  • Могут запросить дополнительные документы
  • Проверят что вид деятельности не в списке запрещённых

После одобрения: получишь доступ к личному кабинету и сможешь настроить платежи.

[ ШАГ 2: ПОЛУЧАЕМ API КЛЮЧИ ]

После одобрения заявки:

  1. Открой личный кабинет ЮKassa
  2. Перейди в раздел Настройки → Ключи API
  3. Найди два ключа:
    • Shop ID (идентификатор магазина) — выглядит как число: 123456
    • Secret Key (секретный ключ) — выглядит как: test_AbCdEf123456...

Куда сохранить:

Добавь в файл .env:

YOOKASSA_SHOP_ID=123456
YOOKASSA_SECRET_KEY=test_AbCdEf123456...

И в Vercel Environment Variables (Settings → Environment Variables → Add):

Name: YOOKASSA_SHOP_ID
Value: 123456

Name: YOOKASSA_SECRET_KEY
Value: test_AbCdEf123456...
⚠️ ВАЖНО:

Секретный ключ никому не показывай! Если кто-то узнает этот ключ, он сможет создавать платежи от твоего имени. А это ваще не прикольно.

[ ШАГ 3: ТЕСТОВЫЙ РЕЖИМ ]

ЮKassa автоматически создает тестовый магазин для проверки интеграции.

Где найти тестовые ключи:

  1. В личном кабинете переключись на Тестовый магазин (переключатель в верхнем меню)
  2. Открой Настройки → Ключи API
  3. Скопируй тестовые ключи (начинаются с test_...)
  4. Добавь в `.env`:
YOOKASSA_TEST_MODE=true
YOOKASSA_TEST_SHOP_ID=тестовый-id
YOOKASSA_TEST_SECRET_KEY=test_ключ

Как тестировать:

В тестовом режиме используй специальные тестовые карты:

  • Успешная оплата: 5555 5555 5555 4477
  • Отклонённая оплата: 5555 5555 5555 4444
  • Срок действия: любая дата в будущем
  • CVC: любые 3 цифры

Платеж обработается как настоящий, но деньги не спишутся.

[ ШАГ 4: ИНТЕГРАЦИЯ С САЙТОМ ]

Теперь нужно добавить код, который будет создавать платежи на твоем сайте. ЮKassa предлагает SDK (готовая библиотека) для разных языков: JavaScript, PHP, Python, Java, C#.

SDK упрощает работу:

  • Готовые функции для создания платежей
  • Автоматическая проверка подписей webhook
  • Документация на русском

Как создать платеж:

Попроси Claude Code создать интеграцию с ЮKassa. Вот промпт:

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

Требования:
1. Используй официальный SDK ЮKassa для JavaScript
2. Создай API функцию api/create-payment.ts которая:
   - Принимает email пользователя
   - Создает платеж на сумму (укажи свою цену)
   - Возвращает ссылку для оплаты
3. Используй переменные окружения:
   - YOOKASSA_SHOP_ID
   - YOOKASSA_SECRET_KEY
4. После создания платежа перенаправь пользователя на страницу оплаты ЮKassa
5. После успешной оплаты верни на страницу /success

Метод оплаты: СБП + банковские карты
Валюта: RUB (рубли)

ВАЖНО: перед началом работы, загугли актуальную инфу, сегодня: [дата].

Что сделает Claude:

  • Установит SDK ЮKassa
  • Создаст функцию создания платежа
  • Добавит кнопку оплаты на сайт
  • Настроит перенаправление на страницу ЮKassa

Протестируй:

  • Нажми кнопку оплаты → откроется страница ЮKassa
  • В тестовом режиме используй тестовую карту: 5555 5555 5555 4477
  • После оплаты вернёшься на страницу успеха

[ ШАГ 5: НАСТРАИВАЕМ WEBHOOK ]

Webhook тут работает так же, как в NowPayments (урок 19). ЮKassa отправляет сообщение на твой сервер с информацией о платеже.

Настройка в ЮKassa:

  1. Открой личный кабинет ЮKassa
  2. Перейди в Настройки → Уведомления
  3. Укажи адрес: https://твой-сайт.vercel.app/api/yookassa-webhook
  4. Включи уведомления для события: payment.succeeded (успешная оплата)

Создание функции webhook:

Попроси Claude Code создать обработчик webhook. Вот промпт:

Создай webhook для ЮKassa чтобы обрабатывать успешные платежи.

Требования:
1. Создай функцию api/yookassa-webhook.ts
2. Проверяй подпись от ЮKassa (SDK делает это автоматически)
3. Обрабатывай событие payment.succeeded
4. При успешной оплате:
   - Получи email из payment.metadata.user_email
   - Обнови пользователя в Supabase: установи is_pro = true
5. Используй SUPABASE_SERVICE_ROLE_KEY для обновления базы
   (это ключ администратора, который может изменять любые записи)

Важно: игнорируй другие события, обрабатывай только payment.succeeded

Что сделает Claude:

  • Создаст функцию webhook
  • Добавит проверку подписи от ЮKassa
  • Настроит обновление базы данных при успешной оплате

Не забудь: добавь SUPABASE_SERVICE_ROLE_KEY в .env и Vercel (как в уроке про Webhook).

[ СТАТУСЫ ПЛАТЕЖА ]

ЮKassa отправляет webhook при каждом изменении статуса:

Статус Что происходит Что делать
pending Платеж создан, клиент ещё не оплатил Жди
waiting_for_capture Деньги заблокированы (двухстадийный платеж) Подтверди платеж через API
succeeded Оплата успешна. Деньги у тебя. ВЫДАЙ ТОВАР
canceled Платёж отменён (время истекло или клиент отказался) Ничего не делай
⚠️ САМОЕ ВАЖНОЕ:

выдавай товар ТОЛЬКО на статусе succeeded.

[ ЧЕКЛИСТ ГОТОВНОСТИ ]

Проверь что всё настроено:

  • Зарегистрирован в ЮKassa (есть ИП/ООО)
  • Прошла модерация (доступ к личному кабинету)
  • Получены API ключи (Shop ID + Secret Key)
  • Ключи добавлены в .env и Vercel Environment Variables
  • Установлен SDK: npm install @yookassa/checkout
  • Создана функция создания платежа (api/create-payment.ts)
  • Создана функция webhook (api/yookassa-webhook.ts)
  • Webhook URL указан в настройках ЮKassa
  • Добавлен SUPABASE_SERVICE_ROLE_KEY (для обновления базы)
  • Протестировано: создай платеж → оплати тестовой картой → проверь что база обновилась

Готово! Теперь твой сайт принимает платежи через СБП и банковские карты.

[ ЧАСТЫЕ ПРОБЛЕМЫ ]

1. "Магазин не прошел модерацию"

Причина: вид деятельности в списке запрещённых товаров или не хватает документов.

Решение:

  • Проверь список запрещённых товаров: yookassa.ru/legal/restrictions
  • Свяжись с поддержкой ЮKassa (в личном кабинете есть чат)

2. "Ошибка: Invalid shop_id or secret_key"

Причина: неправильно скопировал ключи или используешь продакшен ключи в тестовом режиме.

Решение:

  • Проверь что ключи скопированы полностью (без пробелов в начале/конце)
  • В тестовом режиме используй тестовые ключи (начинаются с test_)
  • В продакшен режиме используй продакшен ключи

3. "Webhook не приходит"

Причина: неправильно указан URL или проект не задеплоен на Vercel.

Решение:

  • Убедись что проект задеплоен: https://твой-проект.vercel.app работает
  • Проверь URL webhook: должен быть https://твой-проект.vercel.app/api/yookassa-webhook
  • В настройках ЮKassa должно быть включено уведомление для payment.succeeded
💬 Совет:

Лучшая платежка – это та, которая:

а) позволяет клиенту просто и быстро расстаться с деньгами,

б) стабильно выводит твою прибыль.

Их много, как в РФ так и в любой другой стране. Так что выбор есть! Надо просто поискать, почитать отзывы, изучить их правила и документы, убедиться что ты НЕ хулиганишь (по их меркам), да и всё, по сути.