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

Table of contents

• Обзор возможностей и сценарии применения
• Быстрый старт: ключи, окружения, авторизация
• Создание платежа и подтверждение (3‑D Secure)
• Сохранение способа оплаты и рекурренты
• Вебхуки: события, подпись, повторная доставка
• Возвраты и отмены: частичные/полные
• Тестирование и песочница
• Типовые ошибки и отладка
• Рекомендации по безопасности и соответствию

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

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

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

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

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

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

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

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

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

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

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

1. Ваш бэкенд отправляет запрос «создать платеж» с суммой, валютой, описанием и данными покупателя. Укажите способ подтверждения: redirect/embedded/мобильный.
2. Клиент проходит 3‑D Secure 2 или подтверждение в банке и возвращается по success_url.
3. Итоговый статус приходит вебхуком: 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, конфликт идемпотентности. Имейте справочник кодов ошибок, показывайте пользователю нейтральные сообщения, а детали — в логи/алерты.

Рекомендации по безопасности и соответствию

• Минимизируйте область PCI (используйте hosted/iframe там, где это уместно).
• Регулярно ротируйте ключи, включите alerting при росте отказов/чарджбеков.
• Храните токены в зашифрованном виде, разграничьте доступ сервисов.