WooCommerce: отмена платежа и возврат денег через API и хуки

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

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

Чтобы понять, в чём именно проблема, проверьте:

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

Пошаговое решение: как программно отменить платеж и вернуть деньги

1. Подключение к заказу и проверка статуса

$order = wc_get_order( $order_id );
if ( ! $order ) {
    return new WP_Error( 'invalid_order', 'Заказ не найден' );
}
if ( ! $order->is_paid() ) {
    return new WP_Error( 'not_paid', 'Заказ не оплачен' );
}

2. Запуск возврата средств через метод WooCommerce

WooCommerce 3.0+ предоставляет метод refund() для создания возврата:

$refund = wc_create_refund( array(
    'amount'         => $amount_to_refund, // сумма возврата
    'reason'         => 'Отмена заказа',
    'order_id'       => $order->get_id(),
    'refund_payment' => true, // если возвращать через платежный шлюз
) );

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

3. Хуки для кастомной логики после возврата

Чтобы выполнить дополнительные действия, например, отправлять уведомления, используйте:

add_action( 'woocommerce_order_refunded', 'my_custom_after_refund', 10, 2 );
function my_custom_after_refund( $order_id, $refund_id ) {
    $order = wc_get_order( $order_id );
    // Ваша логика
}

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

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

2. Убедитесь, что у клиента на карте или в платёжной системе средства вернулись (зависит от шлюза).

3. Проверьте логи ошибок и уведомления, если вы их реализовали.

4. Протестируйте на тестовом заказе, чтобы избежать проблем с реальными платежами.

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

• Ошибка "Заказ не найден": неверный ID заказа, проверьте корректность передачи параметров.
• Возврат не создаётся: платежный шлюз не поддерживает возвраты через API — проверьте документацию или используйте ручной возврат.
• Ошибка прав доступа: убедитесь, что используемый код выполняется с админскими правами и что ключи API имеют права на возвраты.
• Возврат создаётся, но деньги не возвращаются: это значит, что опция refund_payment не работает с вашим шлюзом — нужно реализовать вызов API платежной системы отдельно.

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

• Всегда валидируйте данные заказа и пользователя перед выполнением возвратов.
• Ограничьте доступ к функциям возврата только администраторам или доверенным сервисам.
• Логируйте все операции возврата для аудита и отладки.
• Если используете собственные API вызовы платежного шлюза, реализуйте повторные попытки и обработку ошибок.

Сравнение способов реализации возврата