Разработка и интеграция платёжного шлюза в WooCommerce

Интеграция платёжного шлюза в WooCommerce

Клиент приходит с задачей подключить региональный банк, которого нет в списке готовых плагинов. Стандартный WooCommerce не умеет работать с нестандартными API. Начинаются костыли: форки чужих модулей, потеря данных, неработающие возвраты. Мы решаем это раз и навсегда — пишем кастомный gateway под ваш стек, с полным контролем над кодом.

Недавно мы интегрировали шлюз для латвийского банка Citadele: написание gateway-класса заняло три дня, ещё день — отладка вебхуков. После релиза заказчик получил не только работающий плагин, но и полную документацию по эксплуатации. Особенно остро стоит вопрос безопасности: старые плагины не проверяют подписи вебхуков, что открывает путь для фальшивых колбэков. Мы внедряем проверку через hash_equals и строгую валидацию входящих запросов.

Недостатки стандартных плагинов

• Устаревшие версии — многие популярные gateway-плагины не обновлялись годами, используют устаревшие классы вроде WC_API и несовместимы с PHP 8.2+.
• Нет поддержки webhook — половина проблем с оплатой решается правильной обработкой колбэков, но в готовых плагинах её либо нет, либо она кривая.
• Частичные возвраты — если нужно вернуть часть заказа (частичный capture), большинство плагинов просто не вызывают process_refund.
• Сложная кастомизация — допилить свою логику (например, добавить метку платежа в админке) в чужой плагин без риска поломать всё при обновлении — тот ещё квест.

Архитектура кастомного gateway

Базовый класс наследуется от WC_Payment_Gateway. Весь платёжный путь — от редиректа на страницу оплаты до обработки вебхука — замыкается в трёх файлах:

wp-content/plugins/mypay-gateway/
├── mypay-gateway.php # Точка входа, регистрация
├── includes/
│   ├── class-wc-gateway-mypay.php
│   └── class-mypay-api-client.php
└── assets/
    └── js/checkout.js

Класс gateway регистрируется в woocommerce_payment_gateways. В конструкторе мы задаём supports — обязательно ['products', 'refunds'], опционально ['subscriptions']. Вот минимальный набор полей формы:

$this->form_fields = [
    'enabled' => [
        'title' => 'Включить',
        'type' => 'checkbox',
        'default' => 'yes',
    ],
    'title' => [
        'title' => 'Название',
        'type' => 'text',
        'default' => 'Банковская карта',
    ],
    'api_key' => [
        'title' => 'API Key',
        'type' => 'password',
    ],
    'secret_key' => [
        'title' => 'Secret Key',
        'type' => 'password',
    ],
    'testmode' => [
        'title' => 'Тестовый режим',
        'type' => 'checkbox',
        'default' => 'no',
    ],
];

Сравнение популярных платёжных шлюзов

Таблица приблизительная — комиссии меняются. Главное: если у вас высокие требования к надёжности и нужны возвраты, лучше Stripe. Если бюджет ограничен — LiqPay или Fondy, но они без готового плагина.

Типичные ошибки при интеграции

• Неверная проверка подписи вебхука — используем hash_equals для защиты от timing attack.
• Отсутствие обработки статуса pending — заказ может висеть в «Ожидании» вечно, если не обработать колбэк.
• Игнорирование частичных возвратов — клиент не может вернуть часть товара, приходится переделывать.
• Хардкод URL вебхука — при смене домена всё ломается; используем home_url('/wc-api/mypay_callback').

Как обеспечить безопасность вебхуков?

Для защиты от поддельных колбэков мы применяем проверку подписи с помощью hash_equals и HMAC. Дополнительно фильтруем IP-адреса провайдера, логируем все входящие запросы. WordPress Coding Standards рекомендуют проверять nonce и капабилити, но для вебхуков этого недостаточно — нужна криптографическая подпись. Пример проверки:

function verify_webhook_signature($payload, $signature, $secret) {
    $expected = hash_hmac('sha256', $payload, $secret);
    return hash_equals($expected, $signature);
}

Какие тесты мы проводим?

• Юнит-тесты PHPUnit для API-клиента: проверяем корректную сериализацию запросов, обработку ошибок, таймауты.
• Интеграционные тесты в сэндбоксе провайдера с Ngrok: эмулируем полный цикл оплаты, вебхуки, частичные возвраты.
• Ручное тестирование в админке: проверяем кнопку «Возврат», логи, статусы заказов.

Все тесты прогоняются в CI перед деплоем.

Процесс разработки

1. Аналитика — знакомимся с REST API провайдера, собираем требования (одностадийная оплата, подписки, возвраты).
2. Проектирование — рисуем диаграмму состояний заказа, согласовываем схему вебхуков.
3. Реализация — пишем gateway-класс, API-клиент, обработку вебхука. В среднем 2–4 дня на базовую интеграцию.
4. Тестирование — юнит-тесты, ручное тестирование в сэндбоксе с Ngrok.
5. Деплой и документация — заливаем на боевой, обучаем админа, передаём README с примерами запросов.

Что входит в работу

• Полный исходный код плагина в вашем репозитории (GitLab/GitHub).
• Документация по установке, настройке и эксплуатации (README с примерами запросов).
• Обучение администратора работе с плагином (настройка шлюза, просмотр логов, возвраты).
• Гарантийная поддержка 14 дней после сдачи, включая бесплатные доработки по текущему шлюзу.

Сроки и стоимость

Базовая интеграция одного шлюза занимает от 2 до 5 рабочих дней. Стоимость рассчитывается индивидуально — зависит от сложности API провайдера и необходимости дополнительных функций (подписки, мультивалютность). Оценим ваш проект за один рабочий день. Получите консультацию по интеграции вашего шлюза — свяжитесь с нами по email или через форму на сайте. Закажите интеграцию, и мы подготовим предложение.

Гарантии

• Код соответствует WordPress Coding Standards.
• Полная обратная совместимость с WooCommerce 8+.
• Все методы защищены от прямого вызова — используем wp_die с корректными кодами ответа.
• Наши решения проверены на 20+ проектах, включая крупные интернет-магазины с оборотом >$9k–13k./мес.

Свяжитесь с нами, чтобы обсудить ваш проект — мы подготовим предложение и сроки.