跳到主内容
版本: 1.x

网关模板

WooCommerce网关模板提供了一个创建您自己自定义支付网关的起点。该模板包括构建一个完全功能性支付网关所需的所有基础代码和结构。

特性​

完整模板

现成可用的网关结构，包含所有所需方法

POS集成

预配置以兼容WooCommerce POS

自动设置

基于脚本的模板定制

可扩展

易于修改和扩展以适应特定支付提供商

入门指南​

选项1：自动模板生成​

该模板包含一个自动为您的特定网关定制模板的脚本：

  1. 克隆仓库：

    git clone https://github.com/wcpos/woocommerce-gateway-template.git
    cd woocommerce-gateway-template

  2. 运行设置脚本：

    ./create-gateway.sh

  3. 按照提示操作：

    • 输入您的网关名称（如：“我的支付网关”）
    • 输入网关别名（如：“my-payment”）
    • 提供描述
    • 脚本将生成一个定制的插件

选项2：手动模板使用​

如果您更喜欢手动定制：

  1. 下载模板：

  2. 定制模板：

    • 将{{GATEWAY_NAME}}替换为您的网关显示名称
    • 将{{GATEWAY_SLUG}}替换为您的网关唯一标识符
    • 将{{GATEWAY_DESCRIPTION}}替换为您的网关描述

  3. 重命名文件：

    • 将wcpos-{{GATEWAY_SLUG}}.php重命名为与您的网关别名匹配
    • 更新文件头和插件信息

模板结构​

主插件文件​

主插件文件（wcpos-{{GATEWAY_SLUG}}.php）包含：

  • 插件头：WordPress插件信息
  • 网关类：主支付网关类
  • 初始化：插件设置和钩子
  • 集成：WooCommerce POS兼容性

关键组件​

网关类结构：

class WCPOS_Gateway_{{GATEWAY_CLASS}} extends WC_Payment_Gateway {
    // Gateway configuration
    public function __construct() { }
    
    // Admin settings form
    public function init_form_fields() { }
    
    // Process payment (main logic goes here)
    public function process_payment( $order_id ) { }
    
    // POS-specific methods
    public function payment_fields() { }
}

定制指南​

基本配置​

  1. 网关信息：

    $this->id = 'your_gateway_id';
    $this->title = 'Your Gateway Name';
    $this->description = 'Gateway description for customers';
    $this->method_title = 'Admin title';
    $this->method_description = 'Admin description';

  2. 支持的功能：

    $this->supports = array(
        'products',
        'refunds',
        'subscriptions', // if applicable
    );

付款处理​

核心支付逻辑在process_payment()方法中：

public function process_payment( $order_id ) {
    $order = wc_get_order( $order_id );
    
    // Your payment processing logic here
    // Example: API calls, validation, etc.
    
    if ( $payment_successful ) {
        $order->payment_complete();
        return array(
            'result' => 'success',
            'redirect' => $this->get_return_url( $order )
        );
    } else {
        wc_add_notice( 'Payment failed', 'error' );
        return array(
            'result' => 'failure'
        );
    }
}

管理设置​

在init_form_fields()中配置管理员设置：

public function init_form_fields() {
    $this->form_fields = array(
        'enabled' => array(
            'title' => 'Enable/Disable',
            'type' => 'checkbox',
            'label' => 'Enable Your Gateway',
            'default' => 'yes'
        ),
        'api_key' => array(
            'title' => 'API Key',
            'type' => 'text',
            'description' => 'Enter your API key',
            'default' => '',
            'desc_tip' => true,
        ),
        // Add more settings as needed
    );
}

POS集成​

实现POS特定功能：

public function payment_fields() {
    // Custom payment form for POS
    if ( is_admin() && isset( $_GET['page'] ) && $_GET['page'] === 'wc-pos' ) {
        // POS-specific payment fields
        echo '<div class="pos-payment-fields">';
        // Your custom POS interface
        echo '</div>';
    } else {
        // Standard web checkout fields
        parent::payment_fields();
    }
}

开发最佳实践​

代码标准​

  • WordPress编码标准：遵循WordPress PHP编码标准
  • WooCommerce指南：遵循WooCommerce开发实践
  • 安全性：清理输入，验证数据，使用nonces
  • 国际化：使用__()和_e()使字符串可翻译

错误处理​

// Proper error handling
try {
    $result = $this->process_api_call( $data );
    if ( is_wp_error( $result ) ) {
        throw new Exception( $result->get_error_message() );
    }
} catch ( Exception $e ) {
    $order->add_order_note( 'Payment failed: ' . $e->getMessage() );
    wc_add_notice( 'Payment processing error', 'error' );
    return array( 'result' => 'failure' );
}

日志记录​

// Add logging for debugging
if ( $this->debug ) {
    $this->log( 'Payment processing started for order ' . $order_id );
}

private function log( $message ) {
    if ( empty( $this->logger ) ) {
        $this->logger = wc_get_logger();
    }
    $this->logger->info( $message, array( 'source' => $this->id ) );
}

测试您的网关​

开发环境​

  1. 测试模式：始终实现测试/沙盒模式
  2. 调试日志：包含全面的日志以便于故障排查
  3. 错误场景：测试各种失败条件
  4. POS测试：专门在POS环境中测试

测试用例​

  • 成功支付：确认订单正确完成
  • 失败支付：确保正确处理错误
  • 退款：如果支持，测试退款功能
  • 边际情况：用各种订单金额和配置进行测试

部署​

插件打包​

  1. 删除开发文件：清理测试文件和开发工具
  2. 版本控制：更新插件头中的版本号
  3. 文档：包含安装说明的README
  4. ZIP包：创建可安装的zip文件

分发​

  • GitHub发布：使用GitHub发布进行版本管理
  • WordPress插件目录：考虑提交到WordPress.org
  • 私有分发：如有需要，可以托管在自己的服务器上

高级功能​

Webhooks​

获取实时支付更新：

public function handle_webhook() {
    $payload = file_get_contents( 'php://input' );
    $data = json_decode( $payload, true );
    
    // Verify webhook signature
    if ( $this->verify_webhook_signature( $payload ) ) {
        $this->process_webhook_data( $data );
    }
}

订阅支持​

处理定期付款：

// Add subscription support
$this->supports[] = 'subscriptions';
$this->supports[] = 'subscription_cancellation';
$this->supports[] = 'subscription_suspension';

多货币​

处理国际支付：

public function get_supported_currencies() {
    return array( 'USD', 'EUR', 'GBP', 'CAD' );
}

资源​

文档​

模板仓库​

寻求帮助​

获取开发支持：

  • 访问GitHub仓库以获取与模板相关的问题
  • 查看WooCommerce开发者文档以获取API问题
  • 加入WooCommerce开发者社区以获得一般指导

示例网关​

研究这些现有的自定义网关以获得实现示例：