支付模块开发概要与接口设计

这里有个细节要注意：platform_number 用于存储第三方渠道的流水号，这是后续对账的关键；而 platform_status 则需根据上游回调实时同步，避免本地状态与外部不一致。

核心接口设计

发起支付请求

客户端调用此接口获取支付凭证（如二维码链接或跳转 URL）。

接口路径： /order/pay.do

请求参数：

响应示例：

成功返回包含二维码地址的数据结构：

{
  "status": 0,
  "data": {
    "orderNo": "1485158676346",
    "qrPath": "http://img.happymmall.com/qr-1492329044075.png"
  }
}

注意，这里的 qrPath 通常指向 CDN 或对象存储上的资源，通过 Nginx 反向代理解析后返回给前端展示。如果生成失败，应返回明确的错误码：

{
  "status": 1,
  "msg": "支付宝生成订单失败"
}

查询订单支付状态

由于网络波动或异步处理，前端可能需要轮询或主动查询支付结果。

接口路径： /order/query_order_pay_status.do

请求参数：

响应逻辑：

• 若订单存在且已支付，返回 true。
• 若订单不存在或无效，返回错误提示。

// 成功
{"status": 0, "data": true}

// 失败
{"status": 1, "msg": "该用户并没有该订单，查询无效"}

异步回调处理

第三方支付平台（如支付宝）会在支付完成后主动向服务器发送通知。这是确保最终一致性的关键步骤。

接口路径： /order/alipay_callback.do

请求方式： POST (HttpServletRequest)

处理要点：

1. 验签：必须校验回调签名，防止伪造请求。
2. 幂等性：同一个回调可能多次到达，需基于订单号做去重处理，避免重复更新状态或发货。
3. 响应确认：收到有效回调后，必须立即返回 success 字符串。如果不返回，支付宝服务端会认为处理失败并触发重试机制，导致日志刷屏甚至重复扣款风险。

// 成功响应
success

// 失败响应
failed

在实际工程中，建议将回调逻辑放入独立的事务中，先更新本地状态，再触发后续业务（如库存扣减、积分发放），确保数据链路闭环。