Как устроен жизненный цикл платежа: от корзины до выдачи заказа
Интеграция платёжного шлюза связывает три независимых узла: браузер или мобильное приложение клиента, бэкенд вашего сервиса и API ЮKassa. Задача бэкенда — обеспечить строгую консистентность данных. Деньги списываются на стороне банка-эквайера, но выдача цифрового товара, продление подписки или бронирование остатка на складе происходит в вашей базе данных. Если связь прервётся посреди операции, система должна однозначно восстановить состояние без вмешательства службы поддержки.
Процесс оплаты строится по схеме с перенаправлением пользователя (redirect). Сервис не касается конфиденциальных данных банковских карт и не подпадает под строгие требования стандарта PCI DSS, перекладывая ввод реквизитов на защищённый интерфейс ЮKassa. Весь цикл разбивается на последовательные технические этапы:
- Покупатель оформляет заказ в корзине. Бэкенд фиксирует в PostgreSQL запись о заказе в статусе «ожидает оплаты» со списком позиций и финальной суммой.
- Сервер формирует запрос POST к API ЮKassa с уникальным заголовком Idempotence-Key и получает в ответе id платежа и confirmation_url.
- Пользователь перенаправляется на платежную страницу ЮKassa, вводит данные карты, подтверждает операцию кодом из SMS через 3-D Secure или оплачивает через СБП.
- После завершения платежа страница ЮKassa перенаправляет клиента обратно на return_url магазина, где интерфейс отображает экран ожидания подтверждения.
- Параллельно платёжный шлюз отправляет асинхронное уведомление на указанный в настройках адрес вебхука вашего бэкенда.
- Обработчик вебхука немедленно отдаёт HTTP-ответ 200 OK, ставит задачу в очередь фоновых воркеров и запрашивает актуальный статус через прямой запрос к API.
- При подтверждении статуса succeeded транзакция базы данных переводит заказ в статус «оплачен» и запускает доставку или открытие доступа.
Создание платежа: заголовок Idempotence-Key и параметры запроса
Создание платежа начинается с отправки POST-запроса на конечную точку API v3 ЮKassa с авторизацией через HTTP Basic Auth, где логином выступает идентификатор магазина, а паролем — секретный ключ API. Главным элементом надёжности этого запроса является заголовок Idempotence-Key. Это уникальная строка длиной до 64 символов, для которой принято генерировать случайный идентификатор UUID v4. Заголовок гарантирует: сколько бы раз клиентский запрос ни дублировался из-за сетевого сбоя или разрыва сокета, платёжный шлюз создаст ровно один платёж.
Если при отправке запроса ваше приложение получает ошибку соединения или таймаут ожидания ответа, сервис безопасно повторяет исходный запрос с тем же самым Idempotence-Key. ЮKassa распознаёт повторный вызов и возвращает сохранённый ответ первого успешного вызова без повторного списания или создания фантомных транзакций. Подробнее о шаблонах повторных попыток с экспоненциальной задержкой и защите от дублей читайте в статье про идемпотентность и повторы API.
В теле запроса передаются сумма с кодом валюты, объект confirmation с типом redirect и обратным адресом return_url, а также логический флаг capture. Параметр capture со значением true запускает одностадийную оплату, при которой средства списываются с карты сразу после авторизации. Если передать false, платёж перейдёт в двухстадийный режим со статусом waiting_for_capture: средства на счёте покупателя холдируются, а финальное списание подтверждается отдельным запросом после проверки наличия товара. В блоке metadata полезно передать внутренний идентификатор заказа, чтобы легко находить его при получении вебхуков.
Обработка вебхуков: почему нельзя слепо доверять входящему payload
Когда покупатель завершает оплату, ЮKassa отправляет на сервер интернет-магазина HTTP-уведомление типа notification с объектом платежа. Главная ошибка начинающих разработчиков — принимать данные из тела входящего запроса на веру и сразу отгружать товар. Публичный URL вебхука доступен любому внешнему клиенту в интернете. Если злоумышленник подберёт адрес эндпоинта и отправит поддельный JSON со статусом payment.succeeded, доверчивый обработчик откроет доступ к услуге без реального перевода денег.
Для базовой фильтрации трафика можно настроить проверку белого списка официальных IP-диапазонов ЮKassa на уровне сетевого экрана или веб-сервера. Однако эталонная архитектура безопасности строится иначе: входящий вебхук рассматривается лишь как сигнал о том, что статус транзакции изменился. Получив событие, обработчик валидирует базовую структуру, мгновенно отвечает кодом 200 OK и передаёт идентификатор платежа во внутреннюю очередь. Воркер берёт идентификатор и выполняет прямой исходящий запрос GET к API ЮKassa по защищённому TLS-каналу с передачей секретного ключа магазина.
Только данные из ответа официального API считаются доверенными. Приложение сверяет идентификатор заказа в метаданных, сумму с точностью до копеек, валюту и статус платежа с записью в своей локальной базе данных. Подробный разбор защиты хуков, проверки отправителя и валидации полезной нагрузки представлен в материале о безопасности вебхуков и цифровых подписях.
Конечный автомат статусов заказа и защита от гонок в базе данных
В платёжной интеграции необходимо строго разделять статусы платежа в шлюзе и статусы заказа во внутренней учётной системе. В ЮKassa платёж проходит путь от pending до waiting_for_capture, succeeded или canceled. В вашем приложении заказ может иметь расширенную линейку: создан, ожидает оплаты, оплачен, собирается, отменён, возвращён. Связующим звеном выступает конечный автомат (state machine), запрещающий недопустимые переходы — например, переход из статуса «отменён» или «оплачен» повторно в состояние «оплачен».
Классическая проблема асинхронных платежей — состояние гонки (race condition). Покупатель после успешной транзакции немедленно перенаправляется на return_url сайта. В этот же момент шлюз шлёт вебхук. Страница возврата и обработчик вебхука могут параллельно попытаться обновить состояние заказа в базе данных. Если не предусмотреть блокировки, система рискует отправить два подтверждающих письма клиенту или дважды начислить баланс. Для предотвращения коллизий в PostgreSQL используются транзакции с явной пессимистичной блокировкой строки через SELECT ... FOR UPDATE либо идемпотентные условные запросы вида UPDATE orders SET status = 'paid' WHERE id = $1 AND status = 'pending'.
Если входящее уведомление или запрос проверки видит, что заказ уже находится в терминальном статусе «оплачен», воркер безопасно завершает операцию без повторного выполнения бизнес-логики. Такой подход защищает систему от дублирующих вебхуков, которые платёжный шлюз по регламенту повторяет при задержках ответов сервера. Тонкости построения биллинговой логики и управления балансами описаны в руководстве по архитектуре биллинга для SaaS, а для мессенджеров актуальна специфика приёма платежей в телеграм-ботах.
Формирование чеков по 54-ФЗ и проведение возвратов
При приёме платежей от физических лиц в российской юрисдикции закон обязывает формировать фискальные чеки. В интеграции с ЮKassa чеки формируются в рамках единого потока: вы можете подключить облачную онлайн-кассу через сервис ЮKassa или связать шлюз со своей сторонней кассой. При создании платежа или подтверждении холдирования в API передаётся объект с контактными данными покупателя и перечнем позиций. ЮKassa сама передаёт данные в кассу, которая фискализирует операцию и отправляет электронный чек покупателю. Конкретные параметры товарных позиций, признаков способа расчёта и фискальных реквизитов следует сверять с актуальной технической документацией платёжного сервиса и вашей кассы.
Операция возврата средств (refund) строится по аналогичным строгим правилам надёжности. Возврат может быть полным или частичным, если клиент вернул только часть заказа. Для инициализации возврата отправляется запрос POST к методу возвратов с обязательным уникальным заголовком Idempotence-Key, суммой и идентификатором исходного платежа. Сервис должен учитывать следующие инженерные аспекты:
- При полном возврате через настроенную онлайн-кассу данные чека возврата обычно генерируются автоматически на основе исходного платежа.
- При частичном возврате в запросе к API необходимо явно передать список возвращаемых позиций для корректного формирования чека коррекции или возврата прихода.
- Для каждого запроса на возврат генерируется собственный UUID в заголовке Idempotence-Key, чтобы исключить риск двойного перевода денег покупателю при сетевом сбое.
- Статус возврата отслеживается через входящие события webhook или прямой периодический опрос API, так как межбанковское зачисление может занимать некоторое время.
- В базе данных запись о возврате связывается с родительским заказом, а статус заказа переводится в состояние «возвращён» или «частично возвращён» только после подтверждения шлюзом.
Тестирование интеграции: тестовый магазин и краевые сценарии
Перед запуском боевого приёма платежей интеграция обязана пройти сквозную проверку в тестовом контуре ЮKassa. Для этого в личном кабинете регистрируется тестовый магазин, предоставляющий отдельные ключи авторизации. Платёжная форма в тестовом режиме полностью имитирует реальный интерфейс, но вместо реальных списаний использует тестовые банковские карты из официального руководства разработчика. Тестовые карты позволяют сымитировать как идеальный платёж, так и все возможные сценарии отказа.
Инженерное тестирование должно проверять не только счастливый сценарий (happy path), но и пограничные сбои сетевой инфраструктуры и пользовательского поведения. В чек-лист обязательной проверки перед релизом входят ключевые этапы:
- Успешная оплата с прохождением 3-D Secure и мгновенным получением вебхука payment.succeeded.
- Отказ в транзакции при использовании тестовой карты с имитацией недостатка средств или истекшего срока действия: корректный перевод заказа в статус ошибки.
- Симуляция потери сетевого соединения при отправке запроса на создание платежа: проверка работы повтора с сохранённым Idempotence-Key без задвоения записи.
- Имитация недоступности вебхука: задержка ответа 200 OK и проверка устойчивости фонового механизма верификации статуса.
- Повторная отправка идентичного вебхука: проверка того, что база данных не начисляет заказ второй раз и сохраняет консистентность.
- Проведение полного и частичного возврата в тестовом режиме с проверкой смены внутреннего статуса заказа.
Готовые плагины для CMS или заказная разработка интеграции
Для типовых интернет-магазинов на популярных платформах (WordPress, Tilda, 1C-Битрикс) ЮKassa предлагает готовые официальные модули. Если проект укладывается в стандартный сценарий корзины без сложной бизнес-логики, готовый плагин подключается за считанные часы и не требует написания бэкенд-кода. Однако по мере роста бизнеса и усложнения бизнес-процессов коробочные решения начинают ограничивать проект.
Кастомная разработка платёжного шлюза на базе Go или Node.js необходима, когда оплата встроена в сложный сервис: рекуррентные подписки, холдирование с динамическим списанием по факту оказания услуг, маркетплейсы со сплитованием платежей, веб-сервисы с личными кабинетами или интеграция с нестандартными CRM и ERP системами. В таких архитектурах критически важна абсолютная прозрачность транзакций, кастомный аудит и отказоустойчивость. Наша студия реализует заказные интеграции платёжных систем, проектируя отказоустойчивые бэкенды под высокие нагрузки.
- Готовый плагин для CMS: подходит для типовых магазинов, витрин с фиксированными ценами, простых форм оплаты и быстрого тестирования ниши.
- Кастомная интеграция через API: необходима для SaaS-платформ, мобильных бэкендов, нестандартных систем лояльности и сложной логики холдирования.
- Собственные очереди и микросервисы: требуются при высокой интенсивности платежей, когда отказ платёжного контура не должен блокировать работу всего сайта.