12 KiB

Raw Permalink Blame History

Yoone Moneris 支付网关技术文档

1. 插件概述

Yoone Moneris 支付网关是一个专为 WooCommerce 设计的支付处理插件，与 Yoone Subscriptions 订阅系统无缝集成，实现信用卡令牌化存储和自动续费功能。本插件支持 Moneris 信用卡支付，并提供完整的订阅支付解决方案。

1.1 核心功能

支持 Yoone Subscriptions 订阅系统的自动续费
信用卡支付令牌化存储
安全的客户支付信息管理
支付失败自动重试机制
与 WooCommerce Subscriptions 插件的兼容性
完整的支付日志记录

2. 系统架构

2.1 整体架构

Yoone Moneris 支付网关采用分层架构设计，与 Yoone Subscriptions 插件紧密集成：

┌─────────────────────────┐
│  WooCommerce 前端界面  │
└────────────────┬────────┘
                 ↓
┌─────────────────────────┐     ┌─────────────────┐
│ Yoone Subscriptions     │────▶│  订阅管理系统   │
└────────────────┬────────┘     └─────────────────┘
                 ↓
┌─────────────────────────┐     ┌─────────────────┐
│ Yoone Moneris 支付网关   │────▶│   Moneris API   │
└─────────────────────────┘     └─────────────────┘

2.2 模块关系

订阅系统：管理订阅计划和生命周期
支付网关：处理支付交易和令牌化
Moneris API：与 Moneris 支付处理系统通信
令牌存储：安全保存客户支付令牌
定时任务：处理自动续费和失败重试

3. 支付令牌化实现

3.1 令牌化流程

令牌化是实现自动续费的关键技术，流程如下：

首次支付流程
- 客户在结账页面输入信用卡信息
- 支付信息通过安全通道发送到 Moneris
- Moneris 处理支付并返回支付令牌
- 支付令牌安全存储在 WordPress 数据库中
令牌存储机制
- 使用 WooCommerce 支付令牌系统存储令牌信息
- 令牌关联到客户账户和订阅记录
- 实际信用卡信息不会存储在本地系统

3.2 技术实现细节

// 首次支付时保存支付令牌
public function save_payment_token_for_subscription( $order_id ) {
    $order = wc_get_order( $order_id );
    
    // 检查订单是否包含订阅商品
    if ( ! $order || ! self::order_contains_subscription( $order ) ) {
        return;
    }
    
    // 获取支付方式和网关
    $payment_method = $order->get_payment_method();
    $gateway = WC()->payment_gateways()->get_available_payment_gateways()[ $payment_method ] ?? null;
    
    // 验证支付网关支持订阅功能
    if ( ! $gateway || ! self::gateway_supports_subscriptions( $payment_method ) ) {
        return;
    }
    
    // 获取支付令牌
    $payment_token = null;
    
    // 从订单元数据获取令牌
    $token_id = $order->get_meta( '_payment_token_id' );
    if ( $token_id ) {
        $payment_token = WC_Payment_Tokens::get( $token_id );
    }
    
    // 如果没有找到令牌，尝试从网关获取
    if ( ! $payment_token && method_exists( $gateway, 'get_order_payment_token' ) ) {
        $payment_token = $gateway->get_order_payment_token( $order );
    }
    
    // 保存令牌到订阅记录
    if ( $payment_token ) {
        $subscriptions = self::get_subscriptions_for_order( $order_id );
        
        foreach ( $subscriptions as $subscription_id ) {
            update_post_meta( $subscription_id, '_payment_token_id', $payment_token->get_id() );
            update_post_meta( $subscription_id, '_payment_method', $payment_method );
        }
    }
}

4. 自动续费机制

4.1 续费处理流程

自动续费是订阅系统的核心功能，由定时任务触发：

续费触发
- WordPress Cron 系统按计划触发续费任务
- 检查每个订阅的下次支付日期
- 对到期订阅执行续费处理
支付处理
- 从订阅记录获取保存的支付令牌
- 创建续费订单
- 使用令牌进行自动扣款
- 处理支付结果（成功/失败）
状态更新
- 支付成功：更新订阅状态和下次续费日期
- 支付失败：安排重试或暂停订阅

4.2 技术实现细节

// 处理订阅续费
public function process_subscription_renewal( $subscription_id ) {
    $subscription = get_post( $subscription_id );
    
    if ( ! $subscription || 'yoone_subscription' !== $subscription->post_type ) {
        return;
    }
    
    // 获取支付方式和令牌
    $payment_method = get_post_meta( $subscription_id, '_payment_method', true );
    $payment_token_id = get_post_meta( $subscription_id, '_payment_token_id', true );
    
    if ( ! $payment_method || ! $payment_token_id ) {
        $this->handle_renewal_failure( $subscription_id, '缺少支付方式或支付令牌' );
        return;
    }
    
    // 获取网关和令牌
    $gateway = WC()->payment_gateways()->get_available_payment_gateways()[ $payment_method ] ?? null;
    $payment_token = WC_Payment_Tokens::get( $payment_token_id );
    
    if ( ! $gateway || ! $payment_token ) {
        $this->handle_renewal_failure( $subscription_id, '支付网关或支付令牌无效' );
        return;
    }
    
    // 创建续费订单
    $renewal_order = $this->create_renewal_order( $subscription_id );
    
    if ( ! $renewal_order ) {
        $this->handle_renewal_failure( $subscription_id, '创建续费订单失败' );
        return;
    }
    
    // 处理续费支付
    try {
        $result = $this->process_renewal_payment( $gateway, $renewal_order, $payment_token );
        
        if ( $result ) {
            $this->handle_renewal_success( $subscription_id, $renewal_order );
        } else {
            $this->handle_renewal_failure( $subscription_id, '续费支付处理失败', $renewal_order );
        }
    } catch ( Exception $e ) {
        $this->handle_renewal_failure( $subscription_id, '续费支付异常: ' . $e->getMessage(), $renewal_order );
    }
}

5. 支付失败处理机制

5.1 失败重试策略

支付失败是订阅系统中常见的情况，系统实现了智能重试机制：

重试配置
- 最大重试次数：3次
- 重试间隔：24小时
- 超过重试次数后可自动暂停订阅
失败处理流程
- 支付失败时，订阅状态设为暂停
- 记录失败原因到订阅日志
- 发送失败通知给客户
- 安排下次重试任务
客户通知
- 发送支付失败邮件，提醒客户更新支付方式
- 提供方便的支付信息更新入口

5.2 技术实现细节

// 处理续费失败
private function handle_renewal_failure( $subscription_id, $error_message, $renewal_order = null ) {
    // 更新订阅状态为暂停
    update_post_meta( $subscription_id, '_status', 'on-hold' );
    
    // 添加失败记录
    $this->add_subscription_note( $subscription_id, '续费失败: ' . $error_message );
    
    // 如果有续费订单，设置为失败状态
    if ( $renewal_order ) {
        $renewal_order->update_status( 'failed', '续费支付失败: ' . $error_message );
    }
    
    // 安排重试（24小时后）
    wp_schedule_single_event( time() + DAY_IN_SECONDS, 'yoone_subscription_process_renewal', [ $subscription_id ] );
    
    // 发送续费失败邮件
    do_action( 'yoone_subscription_renewal_failed', $subscription_id, $error_message, $renewal_order );
}

6. 与 WooCommerce Subscriptions 的兼容性

插件设计为与 WooCommerce Subscriptions 插件完全兼容，实现了双向集成：

兼容性功能
- 支持 WCS 的订阅管理界面
- 同步处理 WCS 计划支付
- 处理支付方式变更
- 共享支付令牌系统
集成实现
- 提供 WCS 支持标记
- 处理 WCS 续费订单
- 同步支付状态

6.1 技术实现细节

// 处理 WooCommerce Subscriptions 续费订单
public function handle_wcs_renewal_order( $renewal_order, $subscription ) {
    // 如果是 Yoone 订阅，同步处理
    $yoone_subscription_id = $subscription->get_meta( '_yoone_subscription_id' );
    
    if ( $yoone_subscription_id ) {
        $renewal_order->add_meta_data( '_yoone_subscription_renewal', $yoone_subscription_id );
        $renewal_order->save();
    }
    
    return $renewal_order;
}

// 处理 WooCommerce Subscriptions 计划支付
public function handle_wcs_scheduled_payment( $subscription_id ) {
    $subscription = wcs_get_subscription( $subscription_id );
    
    if ( ! $subscription ) {
        return;
    }
    
    $yoone_subscription_id = $subscription->get_meta( '_yoone_subscription_id' );
    
    if ( $yoone_subscription_id ) {
        // 触发 Yoone 订阅续费处理
        do_action( 'yoone_subscription_process_renewal', $yoone_subscription_id );
    }
}

7. 安全考虑

7.1 支付安全措施

信用卡信息通过加密通道传输
不存储实际信用卡信息，仅保存支付令牌
遵循 PCI DSS 合规标准
使用 WooCommerce 安全令牌存储机制
定期安全审计和更新

7.2 数据保护

支付令牌存储在 WordPress 安全的用户元数据中
使用 WordPress 的数据验证和转义机制
访问控制限制对支付数据的访问
敏感操作记录详细日志

8. Moneris API 集成

8.1 API 连接配置

API 端点：Moneris 测试/生产环境端点
凭证管理：商户ID和API令牌安全存储
请求格式：XML/JSON请求格式
响应处理：标准化响应解析

8.2 主要 API 功能

支付处理：单次支付和授权
令牌创建：信用卡令牌化
令牌支付：使用令牌进行支付
交易查询：获取交易状态
退款处理：处理退款请求

9. 安装与配置

9.1 系统要求

WordPress 6.4 或更高版本
WooCommerce 8.0 或更高版本
PHP 7.4 或更高版本
Yoone Subscriptions 插件
SSL 证书（必需，用于安全支付）

9.2 配置步骤

安装并激活 Yoone Subscriptions 插件
安装并激活 Yoone Moneris 支付网关插件
在 WooCommerce 设置中配置 Moneris 凭证
启用订阅支持选项
配置支付选项和退款政策
测试支付流程

10. 开发与扩展

10.1 可用钩子

插件提供了多个钩子用于扩展功能：

yoone_moneris_payment_processed：支付处理完成后触发
yoone_moneris_token_saved：支付令牌保存后触发
yoone_moneris_renewal_before_process：续费处理前触发
yoone_moneris_renewal_after_process：续费处理后触发
yoone_moneris_payment_failed：支付失败时触发

10.2 自定义开发

添加自定义支付验证
集成第三方通知系统
自定义支付成功/失败页面
扩展支付网关功能

11. 性能优化

11.1 性能考量

优化 API 请求频率
使用缓存减少重复请求
异步处理非关键操作
定时任务优化
数据库查询优化

12. 故障排除

12.1 常见问题

支付失败：检查信用卡信息、余额和有效期
令牌创建失败：验证 Moneris 凭证和 API 端点
自动续费失败：检查支付令牌状态和有效性
定时任务不执行：验证 WordPress Cron 设置

12.2 日志系统

详细的支付处理日志
错误捕获和记录
订阅状态变更日志
API 通信日志

13. 总结

Yoone Moneris 支付网关为 WooCommerce 电商平台提供了完整的订阅支付解决方案，通过安全的令牌化机制和可靠的自动续费功能，满足了订阅业务的核心需求。插件设计为高度可扩展，同时保持与 WooCommerce 生态系统的兼容性，为商家提供灵活而强大的支付工具。

12 KiB Raw Permalink Blame History Unescape Escape