跳到主内容
版本: 1.x

网关模板

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

特性​

  • 完整模板：现成的网关结构，包含所有必需的方法
  • POS 集成：预配置以兼容 WooCommerce POS
  • 自动化设置：基于脚本的模板定制
  • 最佳实践：遵循 WordPress 和 WooCommerce 编码标准
  • 可扩展性：易于修改和扩展以适应特定的支付提供商

开始使用​

选项 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 开发实践
  • 安全性：对输入进行清理，验证数据，使用令牌
  • 国际化：使用 __() 和 _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. 压缩包：创建可安装的压缩文件

分发​

  • 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 开发者社区以获取一般指导

示例网关​

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