微信支付回调接口

类说明

WechatNotify 类处理微信支付的异步回调通知。

重要说明：

此接口由虎皮椒支付平台自动调用，用户无需手动调用
用于处理订单支付成功后的异步通知
系统会自动验证签名、更新订单状态、记录支付日志
具有幂等性，重复回调不会重复处理

微信支付回调

Method : POST

URL : /wp-json/vtheme/v1/orders/wechat-notify

Auth required : False (回调接口不需要认证)

说明：

此接口由虎皮椒支付平台在用户支付成功后自动调用
不需要用户手动触发
系统会进行签名验证确保安全性

回调参数

虎皮椒支付平台会发送以下参数：

json

{
  "trade_order_id": "ORD202301011200001234",
  "transaction_id": "4200001234567890",
  "status": "OD",
  "order_date": "2023-01-01 12:00:00",
  "total_fee": "100.00",
  "hash": "xxx_signature_hash"
}

参数说明：

trade_order_id : 商户订单号
transaction_id : 第三方支付平台交易号
status : 订单状态，OD=已支付
order_date : 支付时间
total_fee : 支付金额（元）
hash : 签名哈希值

Success Response

Code : 200 OK

Content : success

说明： 返回字符串 success 表示处理成功

Error Response

Code : 400 Bad Request

Content examples :

json

{
  "code": "invalid_request",
  "message": "Invalid request",
  "data": {
    "status": 400
  }
}

json

{
  "code": "signature_verification_failed",
  "message": "Signature verification failed",
  "data": {
    "status": 400
  }
}

Code : 404 Not Found

Content example :

json

{
  "code": "order_not_found",
  "message": "Order not found",
  "data": {
    "status": 404
  }
}

Code : 500 Internal Server Error

Content example :

json

{
  "code": "process_failed",
  "message": "具体错误信息",
  "data": {
    "status": 500
  }
}

处理流程

当虎皮椒支付平台调用此接口时，系统会执行以下步骤：

记录日志：将回调数据写入日志文件
验证参数：检查必要参数是否存在
验证签名：使用配置的APPSECRET验证签名哈希
检查状态：确认订单状态为已支付（OD）
查询订单：根据订单号查询本地订单
幂等性检查：如果订单已完成，直接返回成功
更新订单：将订单状态更新为 completed
记录日志：插入支付日志记录
提交事务：完成所有数据库操作

安全机制

1. 签名验证

系统会使用配置的 APPSECRET 对回调数据进行签名验证：

php

$hash = \XH_Payment_Api::generate_xh_hash($data, $appsecret);
if ($data['hash'] != $hash) {
    // 签名验证失败
    return error;
}

2. 幂等性处理

如果订单已经完成，直接返回成功，避免重复处理：

php

if ($order['order_type'] === 'completed' || $order['order_type'] === 'wait-send') {
    return success;
}

3. 事务保护

所有数据库操作都在事务中执行，确保数据一致性：

php

$wpdb->query("START TRANSACTION");
try {
    // 更新订单
    // 记录日志
    $wpdb->query("COMMIT");
} catch (\Exception $e) {
    $wpdb->query("ROLLBACK");
    return error;
}

4. 日志记录

所有回调都会记录到日志文件：

文件位置：/api/wechat-notify.log
记录内容：时间戳、回调数据、处理结果

订单状态说明

订单可能的状态：

wait-pay : 待支付
wait-send : 待发货（余额支付已完成）
completed : 已完成（在线支付已完成）
cancelled : 已取消

注意事项

接口用途：
- 此接口仅供虎皮椒支付平台调用
- 用户不应手动调用此接口
- 前端应该通过轮询查询订单状态
幂等性：
- 接口具有幂等性，重复调用不会产生副作用
- 已完成的订单不会重复处理
- 保证数据一致性
安全性：
- 必须进行签名验证
- 防止伪造回调
- 所有操作都有日志记录
错误处理：
- 签名验证失败返回400
- 订单不存在返回404
- 处理失败返回500并回滚事务
响应格式：
- 成功返回字符串 success
- 失败返回字符串 failed 或错误对象
- 虎皮椒平台会根据响应判断是否成功
调试建议：
- 查看日志文件 /api/wechat-notify.log
- 检查订单状态是否正确更新
- 验证支付日志是否生成
配置要求：
- 需要在后台配置虎皮椒支付的 APPID 和 APPSECRET
- 回调URL需要在虎皮椒平台配置
- 确保服务器可以正常访问回调URL

前端轮询示例

由于这是异步回调接口，前端应该通过轮询来检查订单状态：

javascript

// 创建订单后开始轮询
function startOrderPolling(orderId) {
  const maxAttempts = 60; // 最多轮询60次（5分钟）
  let attempts = 0;
  
  const pollInterval = setInterval(() => {
    attempts++;
    
    fetch(`/wp-json/vtheme/v1/orders/${orderId}`, {
      headers: {
        'Authorization': 'Bearer ' + ajax_object.wp_rest_nonce
      }
    })
    .then(response => response.json())
    .then(data => {
      if (data.order_type === 'completed' || data.order_type === 'wait-send') {
        // 支付成功
        clearInterval(pollInterval);
        alert('支付成功！');
        // 跳转到订单详情页或刷新页面
        window.location.reload();
      } else if (attempts >= maxAttempts) {
        // 超时
        clearInterval(pollInterval);
        alert('支付超时，请重新尝试');
      }
    })
    .catch(error => {
      console.error('查询失败:', error);
    });
  }, 5000); // 每5秒查询一次
}

// 使用
const orderId = 123;
startOrderPolling(orderId);

日志示例

成功的回调日志：

2023-01-01 12:00:00 - {"trade_order_id":"ORD202301011200001234","transaction_id":"4200001234567890","status":"OD","order_date":"2023-01-01 12:00:00","total_fee":"100.00","hash":"xxx"}
2023-01-01 12:00:00 - Order processed successfully: ORD202301011200001234

失败的回调日志：

2023-01-01 12:00:00 - {"trade_order_id":"ORD202301011200001234","status":"OD","hash":"wrong_hash"}
2023-01-01 12:00:00 - Hash verification failed

重复回调日志：

2023-01-01 12:00:00 - {"trade_order_id":"ORD202301011200001234","status":"OD","hash":"xxx"}
2023-01-01 12:00:00 - Order already completed: ORD202301011200001234

微信支付回调接口 ​

类说明 ​

微信支付回调 ​

回调参数 ​

Success Response ​

Error Response ​

处理流程 ​

安全机制 ​

1. 签名验证 ​

2. 幂等性处理 ​

3. 事务保护 ​

4. 日志记录 ​

订单状态说明 ​

注意事项 ​

相关接口 ​

前端轮询示例 ​

日志示例 ​

微信支付回调接口

类说明

微信支付回调

回调参数

Success Response

Error Response

处理流程

安全机制

1. 签名验证

2. 幂等性处理

3. 事务保护

4. 日志记录

订单状态说明

注意事项

相关接口

前端轮询示例

日志示例