WooCommerce: отмена и возврат платежей программно с примерами кода

Диагностика проблемы: когда нужно отменять и возвращать платежи программно

В WooCommerce стандартный интерфейс позволяет отменять и возвращать платежи вручную через админку. Однако в ряде случаев это неудобно или невозможно, например, при интеграциях с CRM, автоматических процессах возврата или массовом управлении заказами. В таких сценариях необходимо программное управление отменами и возвратами платежей.

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

Пошаговое решение: программная отмена и возврат платежей

Шаг 1. Получение объекта заказа

Для начала нам нужно получить объект заказа по его ID. Это базовый шаг для любых манипуляций с заказом.

$order_id = 1234; // ID заказа
$order = wc_get_order( $order_id );
if ( ! $order ) {
    return; // заказ не найден
}

Шаг 2. Проверка статуса и возможности возврата

Перед возвратом нужно удостовериться, что заказ оплачен и возврат допустим.

if ( ! $order->has_status( array( 'processing', 'completed' ) ) ) {
    return; // возврат не допустим для текущего статуса
}

Шаг 3. Создание возврата с указанными товарами и суммой

Создаем объект возврата (refund) для заказа. Можно вернуть часть заказа или полный возврат.

$refund_amount = 50; // сумма возврата в валюте магазина
$refund = wc_create_refund( array(
    'amount'         => $refund_amount,
    'reason'         => 'Возврат по заявке клиента',
    'order_id'       => $order_id,
    'refund_payment' => true,
    'restock_items'  => true, // вернуть товары на склад
) );

if ( is_wp_error( $refund ) ) {
    error_log( 'Ошибка при создании возврата: ' . $refund->get_error_message() );
    return;
}

Шаг 4. Обработка статуса заказа после возврата

Если возврат полный, можно перевести заказ в статус "отменен" или "возвращен" в зависимости от логики магазина.

if ( abs( $refund_amount - $order->get_total() ) <= 0.01 ) {
    $order->update_status( 'refunded', 'Заказ полностью возвращен программно' );
} else {
    $order->add_order_note( 'Частичный возврат: ' . wc_price( $refund_amount ) );
}
$order->save();

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

• В админке WooCommerce откройте заказ и убедитесь, что статус изменился корректно (например, «возвращен» или добавлена заметка о частичном возврате).
• Проверьте список возвратов в метаданных заказа — должен появиться новый возврат с нужной суммой.
• Выполните тестовый возврат в платежной системе (например, Stripe или PayPal) и подтвердите, что деньги действительно возвращены покупателю.
• Если используются складские остатки, убедитесь, что товары вернулись на склад.

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

• Ошибка: Возврат создается, но платеж не возвращается.
  Причина: Параметр 'refund_payment' => true не установлен или платежный шлюз не поддерживает автоматический возврат.
  Решение: Убедитесь, что платежный шлюз подключен и поддерживает возвраты через API, и параметр выставлен.
• Ошибка: Статус заказа не меняется после возврата.
  Причина: Отсутствие вызова $order->save() или логика смены статуса не прописана.
  Решение: Добавьте вызов $order->save() после обновления статуса.
• Ошибка: Возврат создается, но товары не возвращаются на склад.
  Причина: Параметр 'restock_items' => true отсутствует.
  Решение: Добавьте этот параметр при создании возврата, если нужно вернуть товары.

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

• Проверяйте права пользователя перед выполнением программного возврата, чтобы избежать несанкционированных операций.
• Логируйте ошибки возвратов и статусы для последующего аудита.
• Используйте транзакции базы данных или WP_Transaction если работаете с критичными изменениями данных.
• Для массовых возвратов реализуйте пакетную обработку с разбивкой по времени, чтобы не перегружать сервер и API платежных систем.

Сравнение подходов к возвратам в WooCommerce

Метод	Описание	Плюсы	Минусы
Ручной возврат через админку	Стандартный интерфейс WooCommerce для возвратов	Простота, не требует кода	Не автоматизируется, неудобен для массовых операций
Программный возврат через wc_create_refund()	Автоматизация возвратов через код	Гибкость, интеграция с внешними системами	Требует знаний, нужно тестировать
Использование сторонних плагинов для возвратов	Расширенные функции возвратов и управления	Дополнительные возможности, поддержка	Зависимость от стороннего кода, нагрузка