Подключение ЮKassa к WooCommerce: оплата, вебхуки, статусы и чеки

ЮKassa в WooCommerce обычно подключают ради простой задачи: покупатель оформляет заказ, оплачивает его, а магазин автоматически понимает, что деньги получены. На практике надёжная интеграция включает больше этапов: создание платежа, возврат пользователя после оплаты, серверное уведомление о результате, смену статуса заказа, работу с повторными уведомлениями и, при необходимости, передачу данных для чека.

Если настроить только красивую кнопку оплаты, можно получить неприятную ситуацию: деньги у клиента списались, а заказ остался в статусе «Ожидает оплаты». Поэтому платёжную интеграцию лучше проектировать как отдельный процесс, а не как одну форму на странице checkout.

Что должно работать после подключения ЮKassa

Минимальная рабочая схема выглядит так:

1. WooCommerce создаёт заказ с уникальным номером;
2. платёжный модуль создаёт платёж в ЮKassa и связывает его с заказом;
3. покупатель проходит оплату доступным способом;
4. ЮKassa сообщает серверу магазина об изменении состояния платежа;
5. WooCommerce обновляет заказ и добавляет техническую запись в order notes;
6. если требуется фискализация, передаются корректные позиции и данные для чека;
7. клиент получает понятный результат оплаты, а менеджер видит реальное состояние заказа.

ЮKassa рекомендует использовать входящие уведомления для отслеживания событий, когда объект API меняется без участия магазина. В документации события имеют формат вроде payment.succeeded или payment.canceled. Официальное описание механизма: входящие уведомления ЮKassa.

Почему нельзя доверять только странице «Спасибо за заказ»

Возврат браузера на страницу success — это часть пользовательского интерфейса, а не достаточное подтверждение оплаты. Пользователь может закрыть вкладку, потерять соединение или вернуться по старой ссылке. Источник истины для автоматической смены статуса должен быть серверным.

Именно поэтому платёжный шлюз должен корректно обрабатывать уведомления от ЮKassa. Если уведомление пришло повторно, код не должен повторно списывать остаток, отправлять второй чек или запускать одну и ту же бизнес-операцию дважды.

Как статусы ЮKassa связать со статусами WooCommerce

У WooCommerce есть собственная модель статусов. Например, Pending payment означает, что заказ создан, но оплата ещё не подтверждена. Processing обычно означает, что платёж получен и физический товар ждёт выполнения. Для заказа, состоящего только из виртуальных и скачиваемых товаров, логика может отличаться.

Официальное описание статусов WooCommerce доступно в документации WooCommerce. Платёжный модуль не должен бездумно переводить любой оплаченный заказ в Completed: статус зависит от типа товара и процесса магазина.

Что такое webhook в этой интеграции

Webhook — это запрос от внешней системы к вашему сайту при наступлении события. В случае платёжной системы это позволяет магазину не опрашивать API каждую минуту, а получить уведомление, когда состояние платежа изменилось.

В WooCommerce webhooks также используются для интеграций со сторонними сервисами. Документация WooCommerce отдельно описывает создание webhook и просмотр логов доставки: WooCommerce Webhooks.

Что проверить в endpoint уведомлений

• URL доступен снаружи по HTTPS;
• WordPress не закрывает endpoint Basic Auth, maintenance-режимом или защитой хостинга;
• Cloudflare/WAF не блокирует запросы платёжной системы;
• обработчик быстро отвечает и не ждёт долгих сторонних операций;
• повтор одного события не создаёт дубли;
• ошибки пишутся в лог без секретных ключей и персональных данных.

Чеки и данные товаров

Платёж и кассовый чек — не одно и то же. В официальной документации ЮKassa отдельно указано, что электронная квитанция от платёжного сервиса не заменяет фискальный чек. Конкретная схема зависит от юридического статуса продавца и используемой кассовой интеграции. Перед запуском нужно проверить названия позиций, количество, стоимость, НДС и другие обязательные параметры для вашей схемы.

Официальная справка: отправка чеков в налоговую через решения ЮKassa.

Типичные ошибки подключения

1. Оплата прошла, заказ остался Pending payment

Сначала проверяют order notes WooCommerce, лог платёжного модуля и факт доставки серверного уведомления. WooCommerce в своей документации по диагностике заказов прямо рекомендует при зависших статусах проверять сообщения платёжного шлюза и webhooks.

2. Статус меняется только после ручного обновления

Это часто указывает на проблему с callback/webhook, фоновой задачей или кэшированием. Проверять нужно не браузер, а серверные логи и фактические входящие запросы.

3. Дублируются письма или действия после оплаты

Причина может быть в том, что одно бизнес-действие повешено одновременно на несколько hooks WooCommerce, либо повторное уведомление воспринимается как новое событие. Идемпотентность здесь обязательна.

4. После обновления WooCommerce оплата перестала работать

Следует проверить совместимость платёжного расширения с текущими версиями WordPress, WooCommerce, PHP и checkout-блоками. Особенно осторожно нужно относиться к кастомизированному checkout и коду, который меняет порядок создания заказа.

Как безопасно тестировать перед запуском

Перед включением оплаты на боевом магазине полезно пройти отдельный тестовый сценарий:

1. создать тестовый товар с понятной ценой;
2. оформить заказ новым клиентом;
3. проверить создание payment ID;
4. проверить успешный платёж;
5. убедиться, что webhook дошёл;
6. сверить order notes и финальный статус;
7. проверить письмо клиенту;
8. проверить чек, если он должен формироваться;
9. проверить отмену или возврат;
10. повторить тест на мобильном checkout.

WooCommerce рекомендует использовать тестовый режим платёжного шлюза, если он доступен, и анализировать статусы и логи при ошибках оплаты.

Когда нужен стандартный модуль, а когда кастомная интеграция

Если у магазина обычный checkout, одна валюта и стандартный сценарий оплаты, разумно начать с поддерживаемого модуля. Кастомная разработка нужна, когда есть сложная логика статусов, собственный личный кабинет, нестандартные позиции в заказе, несколько юридических лиц, внешний ERP/CRM, специфические чеки или отдельный backend.

В A.S Groups такие задачи можно реализовать как часть разработки WooCommerce или как точечную доработку WordPress. Если после оплаты данные должны уходить в CRM, склад или другие сервисы, полезно сразу проектировать интеграцию сайта с CRM.

Чек-лист перед включением ЮKassa на боевом сайте

• HTTPS работает без ошибок;
• секретные ключи не находятся в коде темы или публичном репозитории;
• endpoint уведомлений доступен;
• статусы WooCommerce меняются по подтверждённым событиям;
• повторные уведомления безопасны;
• ошибки пишутся в технический лог;
• чек формируется по правилам вашей схемы;
• возврат протестирован;
• клиентские письма не дублируются;
• checkout проверен на мобильных устройствах.

FAQ

Можно ли подключить ЮKassa к WooCommerce без программиста?

Для стандартного магазина часто достаточно поддерживаемого платёжного расширения и корректной настройки. Разработчик нужен при нестандартном checkout, интеграциях и ошибках серверных уведомлений.

Почему заказ не становится Processing после оплаты?

Нужно проверить order notes, логи платёжного шлюза и доставку webhook. Успешная страница возврата сама по себе не доказывает, что сервер получил подтверждение.

Нужно ли вручную создавать webhook?

Это зависит от конкретного модуля и способа интеграции. Некоторые расширения настраивают уведомления автоматически, в других схемах endpoint регистрируется отдельно.

Можно ли сразу переводить оплаченный заказ в Completed?

Не всегда. Для физических товаров стандартный Processing означает, что оплата получена и заказ ждёт выполнения.

Нужно ли хранить данные банковской карты в WordPress?

Нет. Карточные данные должны обрабатываться платёжной инфраструктурой, а магазину достаточно идентификаторов и статусов платежа.

Что делать, если интеграция уже есть, но работает нестабильно?

Начать с журналов WooCommerce, order notes, логов платёжного модуля и проверки webhook. После этого уже менять код или конфигурацию.

Итог

Хорошее подключение ЮKassa к WooCommerce — это не просто появившийся способ оплаты. Система должна одинаково правильно работать при успешном платеже, отмене, повторном уведомлении, возврате и временной сетевой ошибке. Если нужно подключить или диагностировать оплату на существующем магазине, можно прислать описание текущего checkout и проблему — по схеме будет понятно, где требуется настройка, а где доработка.