WooCommerce: как избежать конфликтов между платёжными шлюзами и кассовыми системами

Диагностика проблемы конфликтов платёжных шлюзов и кассовых систем в WooCommerce

Частая ситуация в интернет-магазинах на WooCommerce — возникновение конфликтов между плагинами платёжных шлюзов и плагинами, интегрирующими кассовые системы (например, онлайн-кассы для ФЗ-54 в РФ). Это проявляется в некорректной обработке оплаты, дублировании чеков, ошибках при завершении транзакции или проблемах с уведомлениями о платеже.

Для выявления источника проблем:

• Активируйте режим отладки WooCommerce (WooCommerce > Настройки > Продвинутые > Логирование).
• Проверьте логи ошибок плагинов платёжных шлюзов и кассовых систем.
• Отключайте плагины по одному, чтобы локализовать конфликт.
• Проверьте совместимость версий плагинов и WooCommerce.

Пошаговое решение для предотвращения конфликтов

1. Контроль порядка выполнения хуков

Платёжные шлюзы и кассовые системы часто используют хук woocommerce_order_status_completed для генерации чеков и обработки заказов. Конфликты возникают, если оба плагина пытаются работать с одним и тем же событием без учёта состояния заказа.

Решение — приоритетное выполнение и проверка состояния заказа в колбэках:

add_action('woocommerce_order_status_completed', 'custom_payment_gateway_handler', 10, 1); // Приоритет 10
add_action('woocommerce_order_status_completed', 'custom_kassa_system_handler', 20, 1); // Приоритет 20

function custom_payment_gateway_handler( $order_id ) {
    $order = wc_get_order( $order_id );
    if ( ! $order || $order->get_meta('_payment_processed') ) {
        return; // Уже обработано
    }
    // Логика обработки платежа
    $order->update_meta_data('_payment_processed', 'yes');
    $order->save();
}

function custom_kassa_system_handler( $order_id ) {
    $order = wc_get_order( $order_id );
    if ( ! $order || $order->get_meta('_kassa_processed') ) {
        return; // Уже обработано
    }
    // Логика генерации чека
    $order->update_meta_data('_kassa_processed', 'yes');
    $order->save();
}

2. Использование нестандартных статусов заказов

Для разграничения обработки платежа и кассового учёта можно добавить пользовательский статус, например, payment_confirmed, и триггерить кассовые операции только после его установки:

// Регистрируем новый статус
function register_payment_confirmed_status() {
    register_post_status( 'wc-payment-confirmed', array(
        'label'                     => 'Оплата подтверждена',
        'public'                    => true,
        'exclude_from_search'       => false,
        'show_in_admin_all_list'    => true,
        'show_in_admin_status_list' => true,
        'label_count'               => _n_noop( 'Оплата подтверждена <span class="count">(%s)</span>', 'Оплата подтверждена <span class="count">(%s)</span>' )
    ) );
}
add_action( 'init', 'register_payment_confirmed_status' );

// Добавляем статус в список WooCommerce
function add_payment_confirmed_to_order_statuses( $order_statuses ) {
    $order_statuses['wc-payment-confirmed'] = 'Оплата подтверждена';
    return $order_statuses;
}
add_filter( 'wc_order_statuses', 'add_payment_confirmed_to_order_statuses' );

// Обработка смены статуса
add_action('woocommerce_order_status_payment-confirmed', 'handle_kassa_after_payment_confirmed');
function handle_kassa_after_payment_confirmed( $order_id ) {
    $order = wc_get_order( $order_id );
    if ( ! $order || $order->get_meta('_kassa_processed') ) {
        return;
    }
    // Вызов кассовой системы
    $order->update_meta_data('_kassa_processed', 'yes');
    $order->save();
}

Проверка результата после внедрения

Чтобы убедиться, что конфликт устранён:

• Создайте тестовый заказ и пройдите оплату через платёжный шлюз.
• Проверьте, что заказ получил правильный статус (completed или пользовательский payment_confirmed).
• Убедитесь, что чек кассовой системы сгенерирован без ошибок (проверьте логи и отчёты онлайн-кассы).
• Проверьте, что в метаданных заказа установлены флаги _payment_processed и _kassa_processed.
• Проверьте, что уведомления клиенту и администратору отправлены корректно.

Частые ошибки и как их исправить

• Отсутствие проверки повторной обработки заказа: если не проверять метаданные, один и тот же заказ обрабатывается несколько раз, что приводит к дублированию чеков или ошибкам. Используйте флаги в метаданных.
• Использование одинаковых приоритетов хука: приоритеты не разграничены, и плагины вмешиваются друг в друга. Задавайте приоритеты явно (например, 10 и 20).
• Несогласованность статусов заказов: если кассовая система реагирует на статус completed, а платёжный шлюз меняет статус на другой, возникает рассинхрон. Добавьте пользовательский статус для последовательной обработки.
• Конфликты AJAX и кеширования: если страница оплаты или подтверждения заказа кешируется, это может блокировать выполнение скриптов. Отключайте кеш для страниц оформления заказа и оплаты.

Практические советы по безопасности и производительности

• Проверяйте данные, приходящие из платёжных шлюзов, на валидность и подпись, чтобы избежать подделки запросов.
• Используйте транзакции базы данных (если есть возможность) при изменении статусов, чтобы избежать частичных обновлений.
• Отделяйте обработку платёжного шлюза и кассовой системы в разные функции с собственными проверками, чтобы минимизировать взаимное влияние.
• Кешируйте результаты вызовов к API онлайн-кассы, если они повторяются, чтобы снизить нагрузку.

Сравнение вариантов решения конфликта