966120
编辑 | blame | 历史 | 原始文档

支付模块 API 接口文档

基础信息

  • 服务地址: http://your-domain:8080
  • 接口协议: HTTP/HTTPS
  • 数据格式: JSON
  • 字符编码: UTF-8

1. 发起微信Native支付

接口说明

生成微信支付二维码，用户扫码后完成支付。

请求信息

  • 请求方式: POST
  • 请求路径: /api/pay/wechat/native
  • Content-Type: application/json

请求参数

参数名 类型 必填 说明 示例
bizOrderId String 是 业务订单号（唯一标识） "ORDER20251123001"
amount Integer 是 支付金额（单位：分） 10000 (表示100元)
subject String 是 订单标题 "商品订单支付"
description String 否 订单描述 "购买商品A×1"
callbackUrl String 是 业务回调地址（支付成功后通知） "https://your-domain.com/notify"

请求示例

{
  "bizOrderId": "ORDER20251123001",
  "amount": 10000,
  "subject": "商品订单支付",
  "description": "购买商品A×1",
  "callbackUrl": "https://your-domain.com/notify"
}

响应参数

参数名 类型 说明
code Integer 响应码，200表示成功
msg String 响应消息
data Object 响应数据
data.orderId Long 支付订单ID
data.transactionId Long 交易流水ID
data.status String 订单状态（PENDING-待支付）
data.qrBase64 String 二维码图片Base64编码
data.expireAt String 过期时间（2小时）

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "orderId": 1234567890,
    "transactionId": 9876543210,
    "status": "PENDING",
    "qrBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "expireAt": "2025-11-23 14:00:00"
  }
}

使用说明

  1. 调用接口获取 qrBase64
  2. 前端直接将Base64显示为图片：<img src="{qrBase64}" />
  3. 用户使用微信扫码支付
  4. 支付成功后，系统会调用您提供的 callbackUrl 通知结果

2. 发起支付宝当面付

接口说明

生成支付宝支付二维码，用户扫码后完成支付。

请求信息

  • 请求方式: POST
  • 请求路径: /api/pay/alipay/precreate
  • Content-Type: application/json

请求参数

与微信支付相同，参考上方表格。

请求示例

{
  "bizOrderId": "ORDER20251123002",
  "amount": 10000,
  "subject": "商品订单支付",
  "description": "购买商品B×1",
  "callbackUrl": "https://your-domain.com/notify"
}

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "orderId": 1234567891,
    "transactionId": 9876543211,
    "status": "PENDING",
    "qrBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "expireAt": "2025-11-23 14:00:00"
  }
}

3. 查询订单状态

接口说明

查询支付订单的当前状态。

请求信息

  • 请求方式: GET
  • 请求路径: /api/pay/orders/{orderId}

路径参数

参数名 类型 必填 说明
orderId Long 是 支付订单ID

请求示例

GET /api/pay/orders/1234567890

响应参数

参数名 类型 说明
code Integer 响应码
msg String 响应消息
data Object 订单详情
data.id Long 订单ID
data.bizOrderId String 业务订单号
data.amount Integer 金额（分）
data.currency String 币种（CNY）
data.channel String 支付渠道（WECHAT/ALIPAY）
data.status String 订单状态
data.subject String 订单标题
data.channelTradeNo String 渠道交易号
data.paidAt String 支付完成时间
data.expireAt String 过期时间
data.createdAt String 创建时间

订单状态说明

状态码 说明
INIT 初始化
PENDING 待支付
SUCCEEDED 支付成功
FAILED 支付失败
CANCELED 已关闭
EXPIRED 已过期

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1234567890,
    "bizOrderId": "ORDER20251123001",
    "amount": 10000,
    "currency": "CNY",
    "channel": "WECHAT",
    "status": "SUCCEEDED",
    "subject": "商品订单支付",
    "channelTradeNo": "4200001234567890",
    "paidAt": "2025-11-23 12:30:00",
    "expireAt": "2025-11-23 14:00:00",
    "createdAt": "2025-11-23 12:00:00"
  }
}

4. 查询最新交易

接口说明

查询订单的最新交易记录（包含二维码）。

请求信息

  • 请求方式: GET
  • 请求路径: /api/pay/orders/{orderId}/transactions/latest

请求示例

GET /api/pay/orders/1234567890/transactions/latest

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 9876543210,
    "orderId": 1234567890,
    "channel": "WECHAT",
    "clientType": "NATIVE",
    "status": "PENDING",
    "qrBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "createdAt": "2025-11-23 12:00:00"
  }
}

5. 业务回调通知（重要）

接口说明

当支付成功后，系统会主动调用您在发起支付时提供的 callbackUrl，通知支付结果。

回调方式

  • 请求方式: POST
  • Content-Type: application/json
  • 请求地址: 您提供的 callbackUrl

请求头

参数名 说明
Content-Type application/json
X-Signature HMAC-SHA256签名，用于验证请求来源
X-Nonce 随机字符串
X-Timestamp 时间戳（毫秒）

回调参数

参数名 类型 说明
tradeId Long 交易ID
orderId Long 订单ID
bizOrderId String 业务订单号
channel String 支付渠道（WECHAT/ALIPAY）
amount Integer 金额（分）
currency String 币种（CNY）
status String 订单状态（SUCCEEDED）
channelTradeNo String 渠道交易号
paidAt String 支付完成时间
subject String 订单标题
description String 订单描述

回调示例

{
  "tradeId": 9876543210,
  "orderId": 1234567890,
  "bizOrderId": "ORDER20251123001",
  "channel": "WECHAT",
  "amount": 10000,
  "currency": "CNY",
  "status": "SUCCEEDED",
  "channelTradeNo": "4200001234567890",
  "paidAt": "2025-11-23 12:30:00",
  "subject": "商品订单支付",
  "description": "购买商品A×1"
}

签名验证

签名算法: HMAC-SHA256

签名数据: payload + nonce + timestamp

验证步骤:
1. 获取请求头中的 X-Signature、X-Nonce、X-Timestamp
2. 获取请求体 JSON 字符串 payload
3. 拼接字符串：signData = payload + nonce + timestamp
4. 使用配置的 callbackSignSecret 计算 HMAC-SHA256
5. 对比计算结果与 X-Signature 是否一致

Java示例代码:
```java
String payload = "请求体JSON字符串";
String nonce = request.getHeader("X-Nonce");
String timestamp = request.getHeader("X-Timestamp");
String signature = request.getHeader("X-Signature");

String signData = payload + nonce + timestamp;
String calculated = SignUtil.hmacSha256(signData, callbackSignSecret);

if (signature.equals(calculated)) {
// 签名验证通过
}
```

响应要求

您的回调接口应返回：
- 成功: HTTP 状态码 200-299
- 失败: 其他状态码（系统会自动重试）

重试机制

如果回调失败，系统会按以下间隔自动重试（最多10次）：
- 立即重试
- 1分钟后
- 5分钟后
- 15分钟后
- 60分钟后

6. 健康检查

接口说明

检查服务是否正常运行。

请求信息

  • 请求方式: GET
  • 请求路径: /api/health

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "status": "UP",
    "service": "dryad-payment",
    "time": "2025-11-23 12:00:00",
    "message": "支付模块服务运行正常"
  }
}

错误码说明

错误码 说明
200 成功
500 服务器内部错误
400 请求参数错误
404 资源不存在

错误响应示例

{
  "code": 500,
  "msg": "支付创建失败: 微信下单失败",
  "data": null
}

集成示例

cURL示例

发起微信支付:
bash curl -X POST http://localhost:8080/api/pay/wechat/native \ -H "Content-Type: application/json" \ -d '{ "bizOrderId": "ORDER20251123001", "amount": 10000, "subject": "商品订单支付", "description": "购买商品A×1", "callbackUrl": "https://your-domain.com/notify" }'

查询订单:
bash curl http://localhost:8080/api/pay/orders/1234567890

JavaScript示例

// 发起支付
async function createPayment() {
  const response = await fetch('http://localhost:8080/api/pay/wechat/native', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      bizOrderId: 'ORDER20251123001',
      amount: 10000,
      subject: '商品订单支付',
      description: '购买商品A×1',
      callbackUrl: 'https://your-domain.com/notify'
    })
  });
  
  const result = await response.json();
  if (result.code === 200) {
    // 显示二维码
    document.getElementById('qrcode').src = result.data.qrBase64;
  }
}

// 查询订单状态
async function queryOrder(orderId) {
  const response = await fetch(`http://localhost:8080/api/pay/orders/${orderId}`);
  const result = await response.json();
  return result.data.status;
}

Java示例

// 发起支付
RestTemplate restTemplate = new RestTemplate();
String url = "http://localhost:8080/api/pay/wechat/native";

Map<String, Object> request = new HashMap<>();
request.put("bizOrderId", "ORDER20251123001");
request.put("amount", 10000);
request.put("subject", "商品订单支付");
request.put("callbackUrl", "https://your-domain.com/notify");

ResponseEntity<Map> response = restTemplate.postForEntity(url, request, Map.class);
Map<String, Object> data = (Map<String, Object>) response.getBody().get("data");
String qrBase64 = (String) data.get("qrBase64");

注意事项

  1. 幂等性: 同一 bizOrderId + channel 重复请求会返回同一订单和二维码
  2. 过期时间: 订单创建后2小时内有效，超时自动过期
  3. 并发控制: 同一订单同时只允许一笔进行中的交易
  4. 回调签名: 务必验证回调签名，防止伪造请求
  5. 金额单位: 所有金额单位均为**分**（例如：100元 = 10000分）
  6. 环境配置: 生产环境请使用HTTPS协议

技术支持

如有问题，请联系技术支持团队。