Этот материал предназначен для разработчиков и интеграторов. Перед внедрением сверяйтесь с официальной документацией YooKassa.
Обзор архитектуры и аутентификации
Интеграция строится вокруг REST API с JSON‑транспортом по HTTPS. Аутентификация может включать передачу идентификатора магазина и секретного ключа (формат и заголовки уточняйте в официальной документации). Все ключи должны храниться в защищённом секрете, а сам трафик — шифроваться.
Рекомендации:
- Разделите тестовые и боевые ключи, используйте отдельные проекты/окружения.
- Настройте ограничение исходящих IP и мониторинг аномальной активности.
Создание платежей: синхронные и асинхронные сценарии
Чаще всего оплата происходит в два шага: инициирование и подтверждение (клиент завершает платёж на стороне провайдера). В запросе создайте объект платежа: сумма, валюта, описание, данные клиента, выбранный метод.
Синхронный сценарий: виджет на вашей странице возвращает результат за сессию.
Асинхронный: вы создаёте платёж, далее отслеживаете статус по webhook.
Трекинг: храните internal order_id и связывайте его с payment_id поставщика.
Подтверждение, отмена и статусы
Платёж может требовать подтверждения (например, при 3‑D Secure или удержании/капче). Обрабатывайте статусы: pending, succeeded, canceled/failed. При отмене корректно информируйте пользователя и пишите техподдержке в спорных случаях.
Возвраты и частичные возвраты через API
Для возврата укажите payment_id и сумму (полную или частичную). Сохраняйте причину и метаданные, чтобы синхронизировать с ERP/бухгалтерией. Не забудьте сформировать корректировочный чек по 54‑ФЗ.
Webhooks: доставка, подпись, ретраи
- Укажите публичный HTTPS‑адрес приёмника.
- Подтверждайте получение кодом 2xx, обрабатывайте повторные доставки (ретраи).
- Проверяйте подпись/секрет, ведите журнал вебхуков: время, payload, ответ.
Идемпотентность и обработка повторов
Используйте идемпотентные ключи (например, хэш заказа) для операций создания платежа/возврата, чтобы повторные запросы не приводили к дублям. Храните статус последней операции по ключу в БД.
Фискальные атрибуты (54‑ФЗ) в запросах
При передаче товарных позиций включайте НДС, признак предмета расчёта, ставку, количество и цену. Убедитесь, что сумма по позициям совпадает с суммой платежа, учитывайте скидки/доставку.
SDK: PHP, Node.js, Python, Java
Используйте официальные SDK (при наличии) или лёгкие HTTP‑клиенты с ретраями и таймаутами. Внедряйте circuit breaker и экспоненциальный backoff на сетевых ошибках.
Примеры запросов/ответов
Пример (схематично):
Создание платежа:
{
"amount": {"value": "1000.00", "currency": "RUB"},
"capture": true,
"description": "Order #12345",
"metadata": {"order_id": "12345"}
}
Ответ (усечённо):
{
"id": "pay_...",
"status": "pending",
"confirmation": {"type": "redirect", "confirmation_url": "https://..."}
}
Тестирование в Sandbox и хранение секретов
- Эмулируйте успешные и отказные платежи, возвраты и таймауты вебхуков.
- Храните ключи в KMS/Vault, применяйте ротацию, не логируйте секреты.
Производительность, таймауты и ретраи
- Таймаут клиента 3–10 c, ретраи с backoff на 429/5xx.
- Асинхронная обработка вебхуков, очередь сообщений для надёжной доставки.
- Метрики: конверсия, доля 3‑D Secure, скорость подтверждения, частота возвратов.
Типичные ошибки и отладка
- 400/422: проверьте обязательные поля и формат суммы/валюты.
- 401/403: ключ/подпись, права или среда (test/prod).
- 409: идемпотентный конфликт — повторите запрос с тем же ключом.
- 500/504: временные проблемы — включите ретраи.
Чек‑лист для релиза в прод
- Идемпотентность реализована, вебхуки обрабатываются повторно.
- Ключи в хранилище секретов, 2FA включена, роли ограничены.
- Сверка платежей автоматизирована, логи и метрики настроены.
- Протестированы все ветки: успех/отказ/возврат/частичный возврат.
Дальше: подключите «Тестовый Sandbox», при необходимости — «Интеграции CMS» и «Мобильные SDK».