Подключить оплату к WooCommerce — это не только вывести кнопку «Оплатить». Надёжная интеграция должна создать платёж, связать его с заказом, обработать успешный и неуспешный результат, принять callback/webhook, не задвоить операцию и правильно изменить статус заказа.
Если у платёжного провайдера нет актуального официального расширения или бизнес использует локальный банк, собственный эквайринг, invoice API или нестандартный сценарий, нужен кастомный payment gateway.
Разберём архитектуру такой интеграции, отличия classic checkout и Checkout Block и ошибки, из-за которых оплата превращается в источник ручной поддержки.
Из чего состоит платёжный модуль
WooCommerce предоставляет Payment Gateway API. Класс шлюза обычно расширяет WC_Payment_Gateway, объявляет настройки и реализует обработку оплаты. Для Checkout Block требуется также регистрация payment method и серверная интеграция с Blocks.
| Слой | Ответственность |
|---|---|
| WooCommerce gateway | Настройки, доступность метода, запуск оплаты |
| API провайдера | Создание и подтверждение платежа |
| Return URL | Возврат пользователя после оплаты |
| Webhook/callback | Серверное подтверждение результата |
| Заказ WooCommerce | Статус, payment ID, заметки и бизнес-процесс |
Надёжный поток оплаты
- CheckoutWooCommerce создаёт заказ и выбирается платёжный метод
- Create paymentСервер отправляет сумму и идентификатор провайдеру
- ОплатаКлиент проходит страницу банка или платёжный интерфейс
- CallbackПровайдер сервер-сервер подтверждает фактический статус
- Order stateWooCommerce один раз применяет корректный итоговый статус
Главный принцип: браузер пользователя не должен быть единственным источником истины о платеже.
Почему нельзя полагаться только на return URL
После оплаты пользователь может закрыть вкладку, потерять интернет или не дождаться возврата в магазин. Если заказ помечается оплаченным только по success URL, часть реальных платежей останется в ожидании.
Надёжный сценарий использует серверный webhook/callback провайдера и при необходимости дополнительную проверку статуса через API.
Защита от повторной обработки
Провайдер может повторять callback, пока не получит ожидаемый HTTP-ответ. Пользователь тоже может несколько раз инициировать оплату. Поэтому обработчик должен быть идемпотентным.
- хранить внешний payment ID в заказе;
- проверять, не применён ли уже финальный статус;
- использовать idempotency key, если API его поддерживает;
- не отправлять повторно чек, письмо или заказ в CRM при дубликате callback.
Classic Checkout и Checkout Block
Официальная документация WooCommerce разделяет Payment Gateway API и интеграцию payment method в Checkout Block. Серверная обработка платежа остаётся связана с gateway API, но для блокового checkout метод дополнительно регистрируется в blocks registry.
Если старый плагин работает только в shortcode checkout, на новом магазине он может не появиться в Checkout Block. Это нужно проверять отдельно.
Что нужно получить от провайдера
- актуальную API-документацию;
- sandbox окружение;
- правила подписи callback;
- список статусов;
- правила возвратов;
- ограничения по валютам и суммам;
- требования к 3-D Secure;
- production credentials после тестов.
Где хранить ключи
Secret key, merchant secret и ключ подписи нельзя отдавать в клиентский JavaScript или коммитить в репозиторий. Они должны оставаться на серверной стороне.
WooCommerce отдельно предупреждает, что direct gateway, принимающий платёжные данные непосредственно на странице магазина, требует более серьёзной серверной безопасности и может затрагивать PCI compliance.
Правильные статусы заказа
Успешный платёж не всегда означает немедленный completed. Для физических товаров WooCommerce обычно продолжает собственный жизненный цикл заказа. Интеграция должна учитывать доставку, ручную проверку, возврат и отмену.
Возвраты
Если API позволяет делать refund, полезно интегрировать возврат прямо в WooCommerce. Тогда менеджеру не нужно отдельно открывать кабинет банка. Но возврат должен выполняться только по официальному API с проверкой суммы и состояния транзакции.
Связь с CRM и складом
Хорошая архитектура разделяет платёж и последующие интеграции. Успешный платёж переводит заказ в ожидаемый статус, а отдельный обработчик отправляет его в CRM или склад. Ошибка внешней CRM не должна мешать callback платежа.
Для комплексных сценариев можно совместить WooCommerce-разработку с CRM-интеграцией.
Как тестировать перед production
- Успешная оплата.
- Отказ банка.
- Отмена пользователем.
- Повторный callback.
- Callback раньше return URL.
- Return URL без callback.
- Неверная подпись.
- Повторное открытие страницы оплаты.
- Refund, если поддерживается.
- Classic и Block Checkout.
Чек-лист перед запуском
- Работает sandbox-платёж и отказ
- Webhook проверяет подпись
- Повторный callback не создаёт дубль
- Статусы WooCommerce соответствуют бизнес-процессу
- Секреты остаются на сервере
- Checkout Block протестирован отдельно
- Логи не содержат card data и ключи
- Production credentials добавлены после тестов
Когда нужен кастомный gateway
- у банка нет поддерживаемого WooCommerce-плагина;
- готовый модуль давно не обновлялся;
- нужен особый invoice/payment-link сценарий;
- требуется связать платёж с внутренней системой;
- нужны специфические callbacks или refund flow.
Когда лучше официальный модуль
Если у провайдера есть актуальное официальное расширение с поддержкой вашей версии WooCommerce и нужных способов оплаты, разумнее начать с него. Кастомная разработка оправдана, когда готовый модуль не закрывает требования.
Частые вопросы
Можно подключить любой банк к WooCommerce?
Если банк предоставляет подходящий API интернет-эквайринга, обычно можно разработать отдельный gateway. Возможности зависят от документации.
Нужен отдельный плагин?
Для кастомной платёжной интеграции это предпочтительный вариант.
Можно принимать callback без пользователя?
Да, callback приходит от сервера провайдера, но его подлинность нужно проверять официальным способом.
Почему заказ остаётся pending?
Причина может быть в недошедшем callback, ошибке подписи, неправильном статусе или исключении в обработчике.
Можно добавить оплату в Checkout Block?
Да, но помимо gateway API нужна отдельная интеграция payment method с Blocks.
Вывод
Надёжная оплата в WooCommerce строится вокруг серверной проверки статуса и идемпотентной обработки событий. Один реальный платёж должен превращаться ровно в один корректно обработанный заказ.
Если нужно подключить банк или payment API, исправить gateway или добавить Checkout Block, можно заказать доработку WooCommerce и прислать документацию платёжной системы в A.S Groups.
Обсуждение
Вопросы и комментарии
Можно уточнить детали статьи или поделиться своим опытом. Первый комментарий проходит проверку.