Этот материал предназначен для разработчиков и интеграторов. Перед внедрением сверяйтесь с официальной документацией YooKassa.
Интеграция строится вокруг REST API с JSON‑транспортом по HTTPS. Аутентификация может включать передачу идентификатора магазина и секретного ключа (формат и заголовки уточняйте в официальной документации). Все ключи должны храниться в защищённом секрете, а сам трафик — шифроваться.
Рекомендации:
Чаще всего оплата происходит в два шага: инициирование и подтверждение (клиент завершает платёж на стороне провайдера). В запросе создайте объект платежа: сумма, валюта, описание, данные клиента, выбранный метод.
Синхронный сценарий: виджет на вашей странице возвращает результат за сессию. Асинхронный: вы создаёте платёж, далее отслеживаете статус по webhook.
Трекинг: храните internal order_id и связывайте его с payment_id поставщика.
Платёж может требовать подтверждения (например, при 3‑D Secure или удержании/капче). Обрабатывайте статусы: pending, succeeded, canceled/failed. При отмене корректно информируйте пользователя и пишите техподдержке в спорных случаях.
Для возврата укажите payment_id и сумму (полную или частичную). Сохраняйте причину и метаданные, чтобы синхронизировать с ERP/бухгалтерией. Не забудьте сформировать корректировочный чек по 54‑ФЗ.
Используйте идемпотентные ключи (например, хэш заказа) для операций создания платежа/возврата, чтобы повторные запросы не приводили к дублям. Храните статус последней операции по ключу в БД.
При передаче товарных позиций включайте НДС, признак предмета расчёта, ставку, количество и цену. Убедитесь, что сумма по позициям совпадает с суммой платежа, учитывайте скидки/доставку.
Используйте официальные 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», при необходимости — «Интеграции CMS» и «Мобильные SDK».