ЮMoney (ЮKassa): прием платежей по API — практическое руководство

Обзор возможностей и сценарии применения

ЮMoney (ЮKassa) — популярная платёжная платформа, предоставляющая богатый API для приема платежей: банковские карты, СБП, кошелёк, Apple Pay/Google Pay, QR‑коды. API строится вокруг ресурсов «платеж» и «возврат», включает поддержку 3‑D Secure 2, токенизации и рекуррентных списаний. Подходит для e‑commerce, подписочных сервисов, маркетплейсов (со сплитом), SaaS.

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

Быстрый старт с песочницей и подробной документацией.
Гибкая модель подтверждения: редирект, виджет/iframe, мобильные SDK.
Сильный инструментарий: вебхуки, идемпотентность, детальные статусы.

Быстрый старт: ключи, окружения, авторизация

Шаги онбординга:

Зарегистрируйтесь, получите идентификаторы магазина и секретные ключи (production/sandbox).
Настройте HTTP‑клиент с базовой авторизацией/подписью запросов, журналируйте correlation_id.
Включите идемпотентность: передавайте уникальный Idempotency‑Key при создании/подтверждении/возврате.
Укажите URL вебхука в кабинете, храните секрет для проверки подписи.

Рекомендации:

Разделите ключи по окружениям, храните в Secrets Manager/Vault.
Ограничьте доступ к ключам и логам (маскирование чувствительных полей).

Создание платежа и подтверждение (3‑D Secure)

Типовой поток:

Ваш бэкенд отправляет запрос «создать платеж» с суммой, валютой, описанием и данными покупателя. Укажите способ подтверждения: redirect/embedded/мобильный.
Клиент проходит 3‑D Secure 2 или подтверждение в банке и возвращается по success_url.
Итоговый статус приходит вебхуком: succeeded/ canceled/ pending.

Практические советы:

Передавайте детализированное описание заказа и receipt‑данные для фискализации (если применимо).
Храните внутренний статус‑маппинг, чтобы корректно обрабатывать pending.

Сохранение способа оплаты и рекурренты

Для подписок после первой успешной аутентификации сохраните токен метода оплаты. Далее создавайте повторные платежи без участия клиента, соблюдая требования к уведомлениям и отказам. Храните ссылку между customer_id и payment_method_id, реализуйте календарь списаний и повторные попытки с увеличением интервала.

Лучшие практики:

Добавляйте soft‑descriptor и понятное описание для снижения чарджбеков.
Введите дневные/недельные лимиты списаний и алерты об аномальной активности.

Вебхуки: события, подпись, повторная доставка

ЮMoney отправляет вебхуки о статусах платежей и возвратов. Обработчик должен:

Проверять подпись/секрет (HMAC/заголовок провайдера).
Быть идемпотентным: если событие приходит повторно — не дублировать операции.
Отвечать 2xx быстро; длительную обработку вынести в фоновые задачи.

Советы по устойчивости:

Логируйте весь вебхук в сырых логах (редактируя чувствительные поля).
Если вебхук недоступен, провайдер может повторять доставку — готовьте ретраи и dead‑letter queue.

Возвраты и отмены: частичные/полные

Поддерживаются полный и частичный возврат, а также отмена авторизации (если сумма захолдирована и еще не захвачена). Рекомендуется:

Сохранять связь refund ↔ payment в БД.
Вести статус‑машину: requested → pending → succeeded/failed.
Делать референсные возвраты (по идентификатору платежа) с идемпотентностью.

Тестирование и песочница

Песочница позволяет эмулировать успешные, неуспешные, 3‑D Secure‑сценарии. Проверьте:

Успешный платеж, отказ по 3‑DS, insufficient_funds, canceled_by_user.
Вебхуки: задержка, повторная доставка, подпись.
Рекуррент: сохранение токена и повторное списание.

Типовые ошибки и отладка

Частые причины отказов: неверная сумма/валюта, истёкший ключ, неверный success_url, конфликт идемпотентности. Имейте справочник кодов ошибок, показывайте пользователю нейтральные сообщения, а детали — в логи/алерты.