Как добавить собственный файл обработки платежей в WooCommerce

Диагностика задачи: зачем нужен собственный файл обработки платежей

WooCommerce по умолчанию использует стандартные механизмы для обработки платежей, встроенные в плагины платежных шлюзов. Иногда требуется добавить кастомную обработку платежа, например, для интеграции с нестандартным API банка или с внутренней системой учета. В таких случаях нужно подключить собственный PHP-файл, который будет обрабатывать запросы после подтверждения платежа, обновлять статус заказа и отправлять уведомления.

Основная сложность — корректно встроить файл в архитектуру WooCommerce, чтобы избежать конфликтов и обеспечить безопасность.

Как добавить собственный файл обработки платежей: пошаговое руководство

1. Создайте файл обработки платежей в теме или плагине

Рекомендуется размещать кастомный файл в дочерней теме или в собственном плагине. Например, создадим файл custom-payment-handler.php в папке плагина my-woocommerce-extensions.

<?php
// custom-payment-handler.php

// Безопасность: отключаем прямой доступ
if (!defined('ABSPATH')) {
    exit; // Exit if accessed directly
}

// Получаем параметры запроса
$order_id = isset($_GET['order_id']) ? intval($_GET['order_id']) : 0;
$payment_status = isset($_GET['status']) ? sanitize_text_field($_GET['status']) : '';

if (!$order_id || !$payment_status) {
    wp_die('Неверные параметры запроса.');
}

// Загружаем заказ
$order = wc_get_order($order_id);
if (!$order) {
    wp_die('Заказ не найден.');
}

// Обрабатываем статус платежа
switch ($payment_status) {
    case 'success':
        $order->payment_complete();
        $order->add_order_note('Платеж успешно обработан кастомным обработчиком.');
        break;
    case 'failed':
        $order->update_status('failed', 'Платеж не прошел.');
        break;
    default:
        wp_die('Неизвестный статус платежа.');
}

// Редирект на страницу благодарности
wp_redirect($order->get_checkout_order_received_url());
exit;

2. Зарегистрируйте пользовательский endpoint для вызова файла

Чтобы обращаться к файлу через URL вида https://site.ru/payment-handler/?order_id=123&status=success, добавим rewrite правило:

add_action('init', function () {
    add_rewrite_rule('^payment-handler/?$', 'index.php?payment_handler=1', 'top');
});

add_filter('query_vars', function ($vars) {
    $vars[] = 'payment_handler';
    return $vars;
});

add_action('template_redirect', function () {
    if (get_query_var('payment_handler')) {
        include plugin_dir_path(__FILE__) . 'custom-payment-handler.php';
        exit;
    }
});

После добавления правил нужно обновить постоянные ссылки (админка → Настройки → Постоянные ссылки → Сохранить изменения).

Как проверить, что решение работает

• Откройте URL https://site.ru/payment-handler/?order_id=ID_ЗАКАЗА&status=success, где ID_ЗАКАЗА — реальный ID заказа в WooCommerce.
• Убедитесь, что статус заказа изменился на «Оплачен» и появилась заметка с текстом «Платеж успешно обработан кастомным обработчиком».
• Проверьте, что происходит редирект на страницу благодарности.
• Повторите с параметром status=failed, статус должен измениться на «Ошибка оплаты».

Частые ошибки и способы их исправления

• Ошибка 404 при обращении к endpoint: не забывайте обновлять правила перезаписи (пересохраните постоянные ссылки в админке).
• Проблемы с безопасностью: прямой доступ к файлу — всегда проверяйте defined('ABSPATH') и другие условия.
• Некорректный ID заказа: проверяйте, что order_id передается числом и существует в базе.
• Статус платежа не распознается: используйте строго заданные значения и фильтруйте входящие данные.

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

• При передаче параметров через URL используйте nonce или иные методы проверки подлинности для защиты от CSRF.
• Не храните логику обработки в файлах, доступных напрямую — подключайте через хуки WordPress.
• Для сложной логики лучше реализовывать полноценный платежный шлюз как плагин с использованием хуков woocommerce_payment_gateways.
• Оптимизируйте операции с заказом, избегайте лишних запросов и кешируйте данные при необходимости.

Сравнение вариантов интеграции кастомной обработки платежей