# WooCommerce Gateway Moneris 令牌化与自动续费实现参考

## 背景意义

### 为什么需要令牌化
- **安全性**：避免存储敏感的信用卡信息
- **合规性**：符合 PCI DSS 标准要求
- **用户体验**：支持一键支付和自动续费
- **业务价值**：提高订阅业务的续费成功率

### 为什么需要自动续费
- **订阅业务**：WooCommerce Subscriptions 的核心功能
- **减少流失**：避免手动续费导致的客户流失
- **现金流**：提供可预测的收入流
- **运营效率**：减少人工干预和客服成本

## 核心概念定义

### 令牌化（Tokenization）
将敏感的支付信息（如信用卡号）替换为安全的令牌（Token），用于后续的支付操作。

### 自动续费（Auto Renewal）
基于已保存的支付令牌，在订阅到期时自动处理续费支付。

## 实现路径对比

| 实现方式 | 适用场景 | 安全级别 | 实现复杂度 | 用户体验 |
|---------|---------|---------|-----------|---------|
| Checkout 令牌化 | 标准电商支付 | 高 | 低 | 优秀 |
| 直接 API 令牌化 | 自定义支付流程 | 高 | 中 | 良好 |
| 临时转永久令牌 | 特殊业务需求 | 高 | 高 | 一般 |

## 使用流程

### 1. Checkout 令牌化流程

#### 步骤说明
1. 用户在结账页面输入支付信息
2. 前端调用 Moneris Checkout API
3. 获取临时令牌
4. 后端将临时令牌转换为永久令牌
5. 保存令牌到用户账户

#### 核心代码示例

```php
/**
 * Checkout 令牌化处理类
 * 负责处理 Moneris Checkout 的令牌化流程
 */
class WC_Gateway_Moneris_Checkout_Credit_Card extends WC_Gateway_Moneris_Credit_Card {
    
    /**
     * 处理支付并创建令牌
     * @param int $order_id 订单ID
     * @return array 支付结果
     */
    public function process_payment($order_id) {
        $order = wc_get_order($order_id);
        
        // 获取 Checkout 响应中的临时令牌
        $temp_token = $this->get_checkout_temp_token();
        
        if ($temp_token && $this->should_tokenize_payment_method()) {
            // 将临时令牌转换为永久令牌
            $permanent_token = $this->create_permanent_token($temp_token, $order);
            
            if ($permanent_token) {
                // 保存令牌到用户账户
                $this->get_payment_tokens_handler()->add_token($order->get_user_id(), $permanent_token);
            }
        }
        
        return $this->process_standard_payment($order);
    }
    
    /**
     * 创建永久令牌
     * @param string $temp_token 临时令牌
     * @param WC_Order $order 订单对象
     * @return WC_Gateway_Moneris_Payment_Token|null
     */
    protected function create_permanent_token($temp_token, $order) {
        try {
            // 调用 Moneris API 创建永久令牌
            $request = $this->get_api()->get_add_token_request($order);
            $request->set_temp_token($temp_token);
            
            $response = $this->get_api()->add_token($request);
            
            if ($response && $response->transaction_approved()) {
                // 创建令牌对象
                return new WC_Gateway_Moneris_Payment_Token(
                    $response->get_payment_token_id(),
                    array(
                        'type'    => 'credit_card',
                        'last4'   => $response->get_masked_pan(),
                        'exp_month' => $response->get_exp_month(),
                        'exp_year'  => $response->get_exp_year(),
                        'card_type' => $response->get_card_type(),
                    )
                );
            }
        } catch (Exception $e) {
            $this->add_debug_message('令牌创建失败: ' . $e->getMessage());
        }
        
        return null;
    }
}
```

### 2. 直接 API 令牌化流程

```php
/**
 * 支付令牌处理器
 * 负责令牌的创建、验证和管理
 */
class WC_Gateway_Moneris_Payment_Tokens_Handler {
    
    /**
     * 创建支付令牌
     * @param WC_Order $order 订单对象
     * @param array $payment_data 支付数据
     * @return WC_Gateway_Moneris_Payment_Token|null
     */
    public function create_token($order, $payment_data) {
        // 检查是否应该进行令牌化
        if (!$this->should_tokenize($order, $payment_data)) {
            return null;
        }
        
        try {
            // 构建令牌化请求
            $request = $this->build_tokenize_request($order, $payment_data);
            
            // 调用 Moneris API
            $response = $this->get_api()->tokenize_payment_method($request);
            
            if ($response && $response->transaction_approved()) {
                // 创建并保存令牌
                $token = $this->build_token_from_response($response);
                $this->add_token($order->get_user_id(), $token);
                
                return $token;
            }
        } catch (Exception $e) {
            $this->log_error('令牌创建失败', $e);
        }
        
        return null;
    }
    
    /**
     * 判断是否应该进行令牌化
     * @param WC_Order $order 订单对象
     * @param array $payment_data 支付数据
     * @return bool
     */
    protected function should_tokenize($order, $payment_data) {
        // 用户选择保存支付方式
        if (!empty($payment_data['save_payment_method'])) {
            return true;
        }
        
        // 订阅订单自动令牌化
        if (function_exists('wcs_order_contains_subscription') && 
            wcs_order_contains_subscription($order)) {
            return true;
        }
        
        // 预授权订单
        if ($this->is_pre_order($order)) {
            return true;
        }
        
        return false;
    }
    
    /**
     * 从 API 响应构建令牌对象
     * @param WC_Moneris_API_Response $response API 响应
     * @return WC_Gateway_Moneris_Payment_Token
     */
    protected function build_token_from_response($response) {
        return new WC_Gateway_Moneris_Payment_Token(
            $response->get_payment_token_id(),
            array(
                'type'      => 'credit_card',
                'last4'     => $response->get_masked_pan(),
                'exp_month' => $response->get_exp_month(),
                'exp_year'  => $response->get_exp_year(),
                'card_type' => $response->get_card_type(),
                'gateway_id' => $this->get_gateway()->get_id(),
                'user_id'   => get_current_user_id(),
            )
        );
    }
}
```

### 3. WooCommerce Subscriptions 集成

```php
/**
 * Moneris 订阅集成类
 * 处理与 WooCommerce Subscriptions 的集成
 */
class WC_Moneris_Payment_Gateway_Integration_Subscriptions {
    
    /**
     * 处理订阅续费
     * @param float $amount 续费金额
     * @param WC_Order $renewal_order 续费订单
     * @return void
     */
    public function process_subscription_payment($amount, $renewal_order) {
        try {
            // 获取父订单的支付令牌
            $subscription = wcs_get_subscription($renewal_order->get_meta('_subscription_renewal'));
            $parent_order = $subscription->get_parent();
            $token = $this->get_order_token($parent_order);
            
            if (!$token) {
                throw new Exception('未找到有效的支付令牌');
            }
            
            // 使用令牌处理续费支付
            $result = $this->process_token_payment($renewal_order, $token, $amount);
            
            if ($result['success']) {
                // 续费成功
                $renewal_order->payment_complete($result['transaction_id']);
                $renewal_order->add_order_note(
                    sprintf('Moneris 自动续费成功 - 交易ID: %s', $result['transaction_id'])
                );
            } else {
                // 续费失败
                $renewal_order->update_status('failed', $result['message']);
            }
            
        } catch (Exception $e) {
            $renewal_order->update_status('failed', '自动续费处理失败: ' . $e->getMessage());
        }
    }
    
    /**
     * 使用令牌处理支付
     * @param WC_Order $order 订单对象
     * @param WC_Gateway_Moneris_Payment_Token $token 支付令牌
     * @param float $amount 支付金额
     * @return array 支付结果
     */
    protected function process_token_payment($order, $token, $amount) {
        // 构建支付请求
        $request = $this->build_payment_request($order, $token, $amount);
        
        // 设置 Credential on File (CoF) 参数
        $request->set_cof_info(array(
            'payment_indicator' => 'R', // R = Recurring (订阅续费)
            'payment_information' => '2', // 2 = Subsequent payment
            'issuer_id' => $token->get_issuer_id(), // 从初始交易获取
        ));
        
        // 调用支付 API
        $response = $this->get_api()->credit_card_purchase($request);
        
        return array(
            'success' => $response && $response->transaction_approved(),
            'transaction_id' => $response ? $response->get_transaction_id() : null,
            'message' => $response ? $response->get_message() : '支付处理失败',
        );
    }
    
    /**
     * 获取订单关联的支付令牌
     * @param WC_Order $order 订单对象
     * @return WC_Gateway_Moneris_Payment_Token|null
     */
    protected function get_order_token($order) {
        $token_id = $order->get_meta('_payment_token_id');
        
        if ($token_id) {
            $tokens = WC_Payment_Tokens::get_customer_tokens($order->get_user_id());
            
            foreach ($tokens as $token) {
                if ($token->get_token() === $token_id && 
                    $token instanceof WC_Gateway_Moneris_Payment_Token) {
                    return $token;
                }
            }
        }
        
        return null;
    }
}
```

### 4. 令牌对象结构

```php
/**
 * Moneris 支付令牌类
 * 继承自 WooCommerce 的支付令牌基类
 */
class WC_Gateway_Moneris_Payment_Token extends WC_Payment_Token_CC {
    
    /** @var string 令牌类型 */
    protected $type = 'moneris_cc';
    
    /**
     * 获取令牌的额外数据
     * @return array
     */
    protected function get_hook_prefix() {
        return 'woocommerce_payment_token_moneris_cc_get_';
    }
    
    /**
     * 验证令牌数据
     * @return bool
     */
    public function validate() {
        if (false === parent::validate()) {
            return false;
        }
        
        // 验证 Moneris 特定字段
        if (!$this->get_token()) {
            return false;
        }
        
        return true;
    }
    
    /**
     * 获取 Moneris 令牌ID
     * @return string
     */
    public function get_moneris_token_id() {
        return $this->get_meta('moneris_token_id');
    }
    
    /**
     * 设置 Moneris 令牌ID
     * @param string $token_id
     */
    public function set_moneris_token_id($token_id) {
        $this->add_meta_data('moneris_token_id', $token_id, true);
    }
    
    /**
     * 获取发卡行ID（用于 CoF）
     * @return string
     */
    public function get_issuer_id() {
        return $this->get_meta('issuer_id');
    }
    
    /**
     * 设置发卡行ID
     * @param string $issuer_id
     */
    public function set_issuer_id($issuer_id) {
        $this->add_meta_data('issuer_id', $issuer_id, true);
    }
}
```

## 端到端流程示例

### 订阅创建到自动续费完整流程

```php
/**
 * 完整的订阅支付流程示例
 */
class Moneris_Subscription_Flow_Example {
    
    /**
     * 步骤1: 用户创建订阅订单
     */
    public function create_subscription_order() {
        // 1. 用户在前端选择订阅产品并结账
        // 2. 系统检测到订阅产品，自动启用令牌化
        // 3. 调用 process_payment 处理初始支付
        
        $order_id = 12345;
        $order = wc_get_order($order_id);
        
        // 检查是否为订阅订单
        if (wcs_order_contains_subscription($order)) {
            // 强制启用令牌化
            add_filter('wc_moneris_tokenize_payment_method', '__return_true');
        }
        
        return $this->gateway->process_payment($order_id);
    }
    
    /**
     * 步骤2: 处理初始支付并保存令牌
     */
    public function process_initial_payment($order) {
        // 1. 处理支付
        $payment_result = $this->process_credit_card_payment($order);
        
        if ($payment_result['success']) {
            // 2. 创建并保存令牌
            $token = $this->create_payment_token($order, $payment_result['response']);
            
            // 3. 将令牌关联到订阅
            $subscriptions = wcs_get_subscriptions_for_order($order);
            foreach ($subscriptions as $subscription) {
                $subscription->update_meta_data('_payment_token_id', $token->get_id());
                $subscription->save();
            }
        }
        
        return $payment_result;
    }
    
    /**
     * 步骤3: 自动续费处理（由 WooCommerce Subscriptions 触发）
     */
    public function process_renewal_payment($amount, $renewal_order) {
        // 1. 获取原始订阅和令牌
        $subscription = wcs_get_subscription($renewal_order->get_meta('_subscription_renewal'));
        $token_id = $subscription->get_meta('_payment_token_id');
        $token = WC_Payment_Tokens::get($token_id);
        
        if (!$token) {
            $renewal_order->update_status('failed', '未找到有效的支付令牌');
            return;
        }
        
        // 2. 使用令牌处理续费
        try {
            $request = $this->build_renewal_request($renewal_order, $token, $amount);
            $response = $this->get_api()->credit_card_purchase($request);
            
            if ($response && $response->transaction_approved()) {
                // 续费成功
                $renewal_order->payment_complete($response->get_transaction_id());
                $renewal_order->add_order_note(
                    sprintf('自动续费成功 - 令牌: %s, 交易ID: %s', 
                        $token->get_token(), 
                        $response->get_transaction_id()
                    )
                );
            } else {
                // 续费失败
                $error_msg = $response ? $response->get_message() : '支付处理失败';
                $renewal_order->update_status('failed', $error_msg);
            }
            
        } catch (Exception $e) {
            $renewal_order->update_status('failed', '续费异常: ' . $e->getMessage());
        }
    }
    
    /**
     * 构建续费支付请求
     */
    protected function build_renewal_request($order, $token, $amount) {
        $request = new WC_Moneris_API_Credit_Card_Purchase_Request();
        
        // 基本支付信息
        $request->set_order_id($order->get_order_number());
        $request->set_amount($amount);
        $request->set_payment_token($token->get_token());
        
        // CoF (Credential on File) 信息 - 用于订阅续费
        $request->set_cof_info(array(
            'payment_indicator' => 'R',  // R = Recurring
            'payment_information' => '2', // 2 = Subsequent payment
            'issuer_id' => $token->get_issuer_id(),
        ));
        
        // 客户信息
        $request->set_customer_info(array(
            'email' => $order->get_billing_email(),
            'phone' => $order->get_billing_phone(),
        ));
        
        return $request;
    }
}
```

## 关键配置与注意事项

### 1. 网关配置要求

| 配置项 | 说明 | 必需性 |
|--------|------|--------|
| Store ID | Moneris 商户标识 | 必需 |
| API Token | API 访问令牌 | 必需 |
| 令牌化支持 | 启用令牌化功能 | 订阅必需 |
| CoF 支持 | Credential on File 支持 | 续费推荐 |
| CSC 验证 | 安全码验证设置 | 可选 |

### 2. 订阅集成配置

```php
/**
 * 订阅功能集成配置
 */
public function configure_subscription_support() {
    // 声明支持的功能
    $this->supports = array(
        'products',
        'subscriptions',
        'subscription_cancellation',
        'subscription_suspension',
        'subscription_reactivation',
        'subscription_amount_changes',
        'subscription_date_changes',
        'multiple_subscriptions',
        'tokenization',
    );
    
    // 注册订阅相关的钩子
    add_action('woocommerce_scheduled_subscription_payment_' . $this->id, 
               array($this, 'process_subscription_payment'), 10, 2);
    
    add_action('wcs_resubscribe_order_created', 
               array($this, 'delete_resubscribe_meta'), 10);
    
    add_filter('wcs_renewal_order_meta_query', 
               array($this, 'remove_renewal_order_meta'), 10);
}
```

### 3. 错误处理与重试机制

```php
/**
 * 续费失败处理
 */
public function handle_renewal_failure($renewal_order, $error_message) {
    // 记录失败原因
    $renewal_order->add_order_note('自动续费失败: ' . $error_message);
    
    // 根据错误类型决定处理策略
    if ($this->is_temporary_error($error_message)) {
        // 临时错误：标记为待重试
        $renewal_order->update_meta_data('_renewal_retry_count', 
            $renewal_order->get_meta('_renewal_retry_count') + 1);
        
        // 安排重试（如果未超过最大重试次数）
        if ($renewal_order->get_meta('_renewal_retry_count') < 3) {
            wp_schedule_single_event(
                time() + (24 * 60 * 60), // 24小时后重试
                'moneris_retry_renewal_payment',
                array($renewal_order->get_id())
            );
        }
    } else {
        // 永久错误：通知客户更新支付方式
        $this->send_payment_method_update_notice($renewal_order);
    }
}
```

## 限制与注意事项

### 技术限制
- **CSC 要求**：如果启用 CSC 验证，可能影响令牌化支付
- **令牌有效期**：需要处理令牌过期和更新
- **网络依赖**：依赖 Moneris API 的可用性

### 合规要求
- **PCI DSS**：必须遵循 PCI 合规标准
- **数据保护**：不得存储敏感的卡片信息
- **用户同意**：令牌化需要用户明确同意

### 最佳实践
- **错误处理**：实现完善的错误处理和重试机制
- **日志记录**：记录关键操作用于调试和审计
- **测试环境**：充分测试令牌化和续费流程
- **监控告警**：监控续费成功率和失败原因

## 参考文档

- [Moneris API 官方文档](https://developer.moneris.com/)
- [WooCommerce Subscriptions 开发文档](https://docs.woocommerce.com/document/subscriptions/)
- [WooCommerce Payment Gateway API](https://docs.woocommerce.com/document/payment-gateway-api/)
- [PCI DSS 合规指南](https://www.pcisecuritystandards.org/)