自定义WooCommerce支付网关在Checkout Blocks中不显示的问题排查

我近期开发了一款适配WooCommerce的自定义支付网关插件，用于对接Xendit平台实现订阅支付。该插件在后台可正常激活，但在使用Checkout Blocks的结账页面中无法显示。相关代码如下：

<?php
/**
 * Plugin Name: Custom Plugin for Woocommerce Subscriptions + Xendit
 * Plugin URI: 
 * Author Name: Emmanuel John Navarro
 * Description: Plugin integration to create subscription based payments with automated integration to Xendit
 * Version 0.1.0
 */

add_action('plugins_loaded', 'woocommerce_xen_payment_init',00);

function woocommerce_xen_payment_init(){
    if(class_exists('WC_Payment_Gateway')){
        #[AllowDynamicProperties]
        class WC_xen_payment extends WC_Payment_Gateway{
            public function __construct() {
                $this->id = 'xen_payment';
                $this->icon = apply_filters('woocommerce_payment_icon', plugins_url() . '/assets/icon.png');
                $this->has_fields = false;
                $this->method_title = __('Credit Cards/E-Wallets','xen-pay-woo');
                $this->method_description = __('Pay Through Credit Cards or E-Wallets Through XENDIT, Personal Information will NOT be stored','xen-pay-woo');
                $this->title = $this->get_option( 'title' );
                $this->description = $this->get_option( 'description' );
                
                $this->instructions =  $this->get_option( 'instructions', $this->description );
                
                $this->init_form_fields();
                $this->init_settings();
            }
            public function init_form_fields(){
                $this->form_fields = apply_filters('xen_pay_fields',array(
                    'enabled' => array(
                        'title' => __('Enable/Disable','xen-pay-woo'),
                        'type' =>'checkbox',
                        'label'=> __('Enable or Disable Payments','xen-pay-woo'),
                        'default'=>'no'
                    ),
                    'title' => array(
                        'title' => __('Payment Gateway Name','xen-pay-woo'),
                        'type' =>'text',
                        'default'=>__('Credit Cards/E-Wallets','xen-pay-woo'),
                        'desc_tip'=> true,
                        'description'=> __('Add a new title for the payment gateway that customers will see in the checkout page','xen-pay-woo')
                    ),
                    'description' => array(
                        'title' => __('Payment Gateway Description','xen-pay-woo'),
                        'type' =>'textarea',
                        'default'=>__('This gateway accepts VISA, MASTERCARD, ETC','xen-pay-woo'),
                        'desc_tip'=> true,
                        'description'=> __('Add a new description for the payment gateway that customers will see in the checkout page','xen-pay-woo')
                    ),
                    'instructions' => array(
                        'title' => __('Instructions','xen-pay-woo'),
                        'type' =>'textarea',
                        'default'=>__('Kindly check your account page and reload to contact your personal graphics manager. Thank you so much for choosing HelloGFX','xen-pay-woo'),
                        'desc_tip'=> true,
                        'description'=> __('Place a product description that will be shown after checkout on EMAIL and THANK YOU PAGE','xen-pay-woo')
                    )
                ));
            }

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

                $this->clear_payment_with_api();

                $order->update_status('pending-payment',  __('Awaiting Payments','xen-pay-woo'));

                $order->reduce_order_stock();
                
                WC()->cart->empty_cart();

                return array(
                    'result'=>'success',
                    'redirect'=>$this->get_return_url($order)
                );
            }
            public function clear_payment_with_api(){

            }
        }
    }
}

add_filter('woocommerce_payment_gateways','add_to_woo_xen_payment');

function add_to_woo_xen_payment( $gateways ){
    $gateways[] = 'WC_xen_payment';
    return $gateways;
}

核心原因分析 #

Checkout Blocks（WooCommerce Blocks组件）和传统短代码结账页面采用完全不同的支付网关加载逻辑，你的插件仅实现了传统结账的支持，同时缺少订阅场景的兼容性声明，导致在Blocks结账页面被过滤隐藏：

1. 未适配WooCommerce Blocks的注册机制
   传统支付网关仅通过woocommerce_payment_gateways过滤器即可在经典结账页面显示，但Checkout Blocks需要额外通过专属动作注册网关的区块支持。

2. 未声明订阅支付兼容性
   作为订阅类网关，未明确告知WooCommerce该网关支持订阅订单，系统会自动在订阅结账场景下隐藏不兼容的网关。

3. 代码存在变量错误
   process_payment方法中把$order_id重新赋值为订单对象，但后续使用未定义的$order变量，会触发PHP报错导致网关加载失败。

4. 图标路径错误
   plugins_url()未传入插件文件路径，会导致图标资源找不到，部分场景下也会影响网关显示。

修复方案 #

修改插件代码，补充Blocks支持、订阅声明，同时修复代码错误：

<?php
/**
 * Plugin Name: Custom Plugin for Woocommerce Subscriptions + Xendit
 * Plugin URI: 
 * Author Name: Emmanuel John Navarro
 * Description: Plugin integration to create subscription based payments with automated integration to Xendit
 * Version 0.1.0
 */

add_action('plugins_loaded', 'woocommerce_xen_payment_init', 10);

function woocommerce_xen_payment_init(){
    if(class_exists('WC_Payment_Gateway')){
        #[AllowDynamicProperties]
        class WC_xen_payment extends WC_Payment_Gateway{
            public function __construct() {
                $this->id = 'xen_payment';
                // 修复图标路径，确保指向插件内的资源
                $this->icon = apply_filters('woocommerce_payment_icon', plugins_url('assets/icon.png', __FILE__));
                $this->has_fields = false;
                $this->method_title = __('Credit Cards/E-Wallets','xen-pay-woo');
                $this->method_description = __('Pay Through Credit Cards or E-Wallets Through XENDIT, Personal Information will NOT be stored','xen-pay-woo');
                
                // 声明支持订阅及相关功能
                $this->supports = array(
                    'products',
                    'subscriptions',
                    'subscription_cancellation',
                    'subscription_suspension',
                    'subscription_reactivation',
                    'subscription_amount_changes',
                    'subscription_date_changes',
                    'subscription_payment_method_change',
                    'subscription_payment_method_change_customer',
                    'subscription_payment_method_change_admin',
                    'multiple_subscriptions'
                );

                $this->title = $this->get_option( 'title' );
                $this->description = $this->get_option( 'description' );
                $this->instructions =  $this->get_option( 'instructions', $this->description );
                
                $this->init_form_fields();
                $this->init_settings();

                // 注册后台设置保存动作
                add_action('woocommerce_update_options_payment_gateways_' . $this->id, array($this, 'process_admin_options'));
            }

            public function init_form_fields(){
                $this->form_fields = apply_filters('xen_pay_fields',array(
                    'enabled' => array(
                        'title' => __('Enable/Disable','xen-pay-woo'),
                        'type' =>'checkbox',
                        'label'=> __('Enable or Disable Payments','xen-pay-woo'),
                        'default'=>'no'
                    ),
                    'title' => array(
                        'title' => __('Payment Gateway Name','xen-pay-woo'),
                        'type' =>'text',
                        'default'=>__('Credit Cards/E-Wallets','xen-pay-woo'),
                        'desc_tip'=> true,
                        'description'=> __('Add a new title for the payment gateway that customers will see in the checkout page','xen-pay-woo')
                    ),
                    'description' => array(
                        'title' => __('Payment Gateway Description','xen-pay-woo'),
                        'type' =>'textarea',
                        'default'=>__('This gateway accepts VISA, MASTERCARD, ETC','xen-pay-woo'),
                        'desc_tip'=> true,
                        'description'=> __('Add a new description for the payment gateway that customers will see in the checkout page','xen-pay-woo')
                    ),
                    'instructions' => array(
                        'title' => __('Instructions','xen-pay-woo'),
                        'type' =>'textarea',
                        'default'=>__('Kindly check your account page and reload to contact your personal graphics manager. Thank you so much for choosing HelloGFX','xen-pay-woo'),
                        'desc_tip'=> true,
                        'description'=> __('Place a product description that will be shown after checkout on EMAIL and THANK YOU PAGE','xen-pay-woo')
                    )
                ));
            }

            public function process_payment($order_id){
                // 修复变量名错误
                $order = wc_get_order($order_id);

                $this->clear_payment_with_api();

                $order->update_status('pending-payment',  __('Awaiting Payments','xen-pay-woo'));
                $order->reduce_order_stock();
                
                WC()->cart->empty_cart();

                return array(
                    'result'=>'success',
                    'redirect'=>$this->get_return_url($order)
                );
            }

            public function clear_payment_with_api(){
                // 此处添加Xendit支付接口对接逻辑
            }

            // 验证网关在订阅场景下的可用性
            public function is_available() {
                $is_available = parent::is_available();
                if ( $is_available && class_exists( 'WC_Subscriptions_Order' ) && WC_Subscriptions_Order::order_contains_subscription( wc()->cart ) ) {
                    return true;
                }
                return $is_available;
            }
        }
    }
}

add_filter('woocommerce_payment_gateways','add_to_woo_xen_payment');

function add_to_woo_xen_payment( $gateways ){
    $gateways[] = 'WC_xen_payment';
    return $gateways;
}

// 注册网关到Checkout Blocks系统
add_action( 'woocommerce_blocks_payment_method_type_registration', 'register_xen_payment_for_blocks' );

function register_xen_payment_for_blocks( $payment_method_registry ) {
    if ( class_exists( 'WC_xen_payment' ) ) {
        $payment_method_registry->register( 'xen_payment' );
    }
}

关键修改说明 #

• 添加订阅支持声明：通过$this->supports数组明确网关支持的订阅功能，让WooCommerce识别其兼容性。
• 注册Blocks支持：通过woocommerce_blocks_payment_method_type_registration动作将网关注册到Blocks系统。
• 修复变量与路径错误：修正process_payment中的变量名问题，同时修复图标资源路径。
• 添加设置保存动作：确保后台网关设置能正常保存生效。

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