Обзор возможностей и сценарии применения
Ю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, конфликт идемпотентности. Имейте справочник кодов ошибок, показывайте пользователю нейтральные сообщения, а детали — в логи/алерты.
Рекомендации по безопасности и соответствию
- Минимизируйте область PCI (используйте hosted/iframe там, где это уместно).
- Регулярно ротируйте ключи, включите alerting при росте отказов/чарджбеков.
- Храните токены в зашифрованном виде, разграничьте доступ сервисов.