如何在 WooCommerce 中检测订单支付状态并实现自动跳转或用户数据更新

在WooCommerce开发中，判断订单是否真正支付成功，是一个常见但容易踩坑的需求。很多开发者会尝试用一些非标准的方法来检测支付状态，比如调用一个不存在的函数，结果自然事与愿违。今天，我们就来梳理一下，如何用官方推荐的标准钩子，准确判断订单支付状态，并基于此实现自动跳转或用户数据更新。

先澄清一个核心误区：WooCommerce并不通过所谓的“支付token”字段直接暴露用户是否完成付款，尤其对于非订阅类的一次性订单。判断支付状态的关键依据，应该是订单本身的支付时间（date_paid），而不是孤立的token存在与否。你之前可能尝试用过的 get_wpmg_woocommerce_payment_tokens 函数，并非WooCommerce官方提供，也未被主流支付网关定义，属于无效调用，需要立即替换为标准、可靠的方式。

✅ 推荐方案：使用官方支付完成钩子

最健壮且语义明确的做法，是在订单真正支付成功后触发逻辑。WooCommerce提供两个关键动作钩子，但它们的用途和触发时机有本质区别：

• woocommerce_thankyou：用户访问订单完成页（/checkout/order-received/）时触发，但不保证支付已到账。例如，货到付款的订单也会触发此钩子，所以用它来判断支付状态并不准确。
• woocommerce_payment_complete：仅当订单状态变为“processing”或“completed”，且date_paid被设置时触发。这才是判断“支付已完成”的黄金标准。

以下是一个生产环境推荐的实现方式，可以直接放到主题的functions.php或一个专用插件中：

// ✅ 在 functions.php 或专用插件中添加
add_action('woocommerce_payment_complete', 'handle_payment_success_and_update_user');

function handle_payment_success_and_update_user($order_id) {
    $order = wc_get_order($order_id);
    if (!$order || !$order->get_date_paid()) {
        return; // 安全兜底：确保支付时间存在
    }

    $user_id = $order->get_customer_id();
    if ($user_id <= 0) {
        return;
    }

    // ✅ 方案1：向用户元数据写入支付状态（可用于后续条件判断）
    update_user_meta($user_id, 'last_payment_status', 'completed');
    update_user_meta($user_id, 'last_payment_date', current_time('mysql'));
    update_user_meta($user_id, 'last_order_id', $order_id);

    // ✅ 方案2：根据业务需要，可在此处触发重定向逻辑（注意：此钩子无输出上下文，不可用 header()）
    // 若需前端跳转，请改用 JS 或配合 AJAX + 会话标记
}

⚠️ 注意：woocommerce_payment_complete 运行于后台，没有HTTP响应上下文，不能直接调用 header() 或 exit。如果你的需求是“用户访问某课程页面时，检查其是否已付费，未付费则跳转至结算页”，那么应该改用前端校验逻辑：

// 示例：在课程页面模板中安全检查并跳转（放在模板顶部，早于任何 HTML 输出）
if (is_singular('sfwd-lessons') || get_post_type() === 'sfwd-lessons') {
    $lesson_id = get_the_ID();
    $user_id   = get_current_user_id();

    if ($user_id > 0) {
        // 查询该用户是否有已支付的关联订单（可根据产品 ID / 课程 ID 关联）
        $paid_order_ids = wc_get_orders([
            'status'    => ['wc-completed', 'wc-processing'],
            'customer'  => $user_id,
            'limit'     => 1,
            'return'    => 'ids',
            'meta_query' => [
                [
                    'key'     => '_billing_email', // 或更精准地关联课程（需自定义订单元字段）
                    'compare' => 'EXISTS'
                ]
            ]
        ]);

        if (empty($paid_order_ids)) {
            wp_redirect('https://xx/checkouts/checkout-page/');
            exit;
        }
    }
}

? 补充说明：关于“Payment Token”

WooCommerce的支付token（如信用卡token）主要用于重复扣款场景，比如订阅。它们由支付网关（如Stripe、PayPal）生成并存储在 wp_woocommerce_payment_tokens 表中。普通的一次性订单，根本不需要也不应该依赖token来判断支付结果。

如果你确实需要查询某个用户的token，应该使用官方提供的方法：

$tokens = WC_Payment_Tokens::get_customer_tokens($user_id, 'stripe'); // 指定网关 ID

但再次强调：token存在 ≠ 订单已支付。它只代表用户曾保存过某种支付方式，跟当前订单是否付款成功完全是两码事。

✅ 总结建议

• ✅ 优先使用 woocommerce_payment_complete 处理支付成功后的数据写入、通知、同步等后台任务。
• ✅ 前端访问控制（如课程页跳转）应在PHP模板中，结合 wc_get_orders() 主动查询用户历史订单状态。
• ❌ 避免虚构函数、依赖未定义的meta字段，或误读token的含义。
• ? 所有重定向必须在输出前执行（wp_redirect() + exit），且不可在AJAX或钩子回调中直接使用 header()。

通过以上方式，你将获得稳定、可维护、且符合WooCommerce最佳实践的支付状态处理逻辑。