自定义WooCommerce支付网关未显示问题求助

咱们一步步拆解你的自定义信用卡支付网关无法显示的原因，下面是最关键的排查点和修复方案：

1. 确认网关已正确注册到WooCommerce #

你当前的代码只定义了网关类，但没有把它添加到WooCommerce的支付网关列表，这是最常见的遗漏点。

在wc_custom_gateway_init函数里，类定义完成后，必须添加注册钩子：

// 在WC_Gateway_custom类定义之后添加
add_filter('woocommerce_payment_gateways', 'wc_add_custom_gateway');
function wc_add_custom_gateway($gateways) {
    $gateways[] = 'WC_Gateway_custom';
    return $gateways;
}

这个钩子告诉WooCommerce："嘿，我有个新的支付网关，把它加进去！"

2. 补全构造函数的必填属性 #

你的构造函数代码不完整，WooCommerce要求网关必须具备几个核心属性，否则会被忽略。完整的构造函数至少要包含这些内容：

public function __construct() {
    $this->id = 'custom'; // 唯一标识，不能和其他网关重复
    $this->icon = null; // 可选：如果有网关图标，填URL即可
    $this->has_fields = true; // 表示需要收集信用卡信息字段
    $this->method_title = '自定义信用卡网关'; // 后台显示的网关名称
    $this->method_description = '通过我们的自定义网关使用信用卡支付'; // 后台描述文本
    $this->supports = array('products'); // 支持的功能，比如refunds（退款）可选

    // 加载网关设置（必须）
    $this->init_form_fields();
    $this->init_settings();

    // 绑定设置保存的钩子
    add_action('woocommerce_update_options_payment_gateways_' . $this->id, array($this, 'process_admin_options'));
}

另外，必须实现init_form_fields方法（哪怕是空的），否则后台设置页面会出错，导致网关不显示：

public function init_form_fields() {
    $this->form_fields = array(
        'enabled' => array(
            'title'       => '启用/禁用',
            'label'       => '启用自定义信用卡网关',
            'type'        => 'checkbox',
            'description' => '',
            'default'     => 'no'
        ),
        // 这里可以添加其他设置项，比如API密钥、测试模式等
    );
}

⚠️ 注意：enabled字段是必须的，默认是禁用状态，你需要到WooCommerce后台的「支付设置」里手动启用这个网关。

3. 检查PHP错误和WooCommerce日志 #

很多时候网关不显示是因为隐藏的PHP语法错误或逻辑错误。你可以开启WordPress的调试模式来排查：
在wp-config.php文件中添加以下代码：

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

然后查看wp-content/debug.log文件，里面会记录所有PHP错误。另外，WooCommerce自带的日志在「WooCommerce > 状态 > 日志」里，找和支付相关的日志文件，看有没有报错信息。

4. 确保代码放置位置正确 #

不建议直接把代码放在主题的functions.php里（容易因主题更新丢失），最好做成独立插件：

1. 创建一个名为wc-custom-credit-card-gateway的文件夹
2. 在文件夹里创建wc-custom-credit-card-gateway.php，开头加上插件头信息：

<?php
/**
 * Plugin Name: WooCommerce自定义信用卡支付网关
 * Description: 适用于WooCommerce 3.0+的自定义信用卡支付网关
 * Version: 1.0.0
 * Author: 你的名字
 * WC requires at least: 3.0.0
 * WC tested up to: 8.0.0
 */

// 先检查WooCommerce是否激活
if (!class_exists('WC_Payment_Gateway')) {
    return;
}

// 初始化网关
add_action('plugins_loaded', 'wc_custom_gateway_init');
function wc_custom_gateway_init() {
    // 这里放你的WC_Gateway_custom类定义、注册钩子等完整代码
}

然后在WordPress后台启用这个插件，稳定性更高。

5. 补全必要的支付处理方法 #

如果你的网关设置了has_fields = true，还需要实现payment_fields方法来显示信用卡表单，否则前端支付页面可能不会加载网关选项：

public function payment_fields() {
    echo '<div class="custom-cc-fields">';
    echo '<p class="form-row form-row-wide">';
    echo '<label for="custom_cc_number">信用卡号 <span class="required">*</span></label>';
    echo '<input type="text" id="custom_cc_number" name="custom_cc_number" required>';
    echo '</p>';
    // 添加有效期、CVV等字段...
    echo '</div>';
}

另外，必须实现process_payment方法来处理支付逻辑，否则即使网关显示了，支付时也会报错：

public function process_payment($order_id) {
    $order = wc_get_order($order_id);

    // 这里写你的支付处理逻辑，比如调用第三方支付API
    // 示例：假设支付成功
    $order->payment_complete();
    $order->add_order_note('通过自定义信用卡网关完成支付');

    // 清空购物车
    WC()->cart->empty_cart();

    // 返回跳转链接
    return array(
        'result' => 'success',
        'redirect' => $this->get_return_url($order)
    );
}

按照上面的步骤补全代码后，刷新WooCommerce后台的支付设置页面，应该就能看到你的自定义网关了。记得在后台启用它，然后测试支付流程。

内容的提问来源于stack exchange，提问作者eComEvo