soul/addons/Universal_Payment_Module copy/1_核心设计_通用协议/API接口定义.md

通用支付模块 API 接口定义 (Universal Payment API) v4.0

无论后端使用何种语言（Python/Node/Go/Java/PHP），请严格实现以下 RESTful 接口

🎯 设计原则

1. RESTful 风格: 资源命名统一，动词语义清晰
2. 统一响应格式: 所有接口返回 {code, message, data} 结构
3. 幂等性: 重复请求不产生副作用
4. 安全性: 敏感操作需签名验证

---

📦 统一响应格式

成功响应

{
  "code": 200,
  "message": "success",
  "data": { ... }
}

错误响应

{
  "code": 400,
  "message": "参数错误：order_sn 不能为空",
  "data": null
}

常用错误码

Code	含义
200	成功
400	请求参数错误
401	未授权/登录过期
403	无权限
404	资源不存在
409	状态冲突 (如重复支付)
500	服务器内部错误

---

1. 核心交易接口 (Core Transaction)

1.1 创建订单

业务系统调用，创建一个待支付订单。

POST /api/payment/create_order
Content-Type: application/json
Authorization: Bearer {token}

Request Body:

{
  "user_id": "u1001",             // [必填] 用户ID
  "title": "VIP会员月卡",          // [必填] 订单标题 (≤30字符)
  "amount": 99.00,                // [必填] 金额 (单位: 元)
  "currency": "CNY",              // [可选] 币种，默认 CNY
  "product_id": "vip_monthly",    // [可选] 商品ID
  "product_type": "membership",   // [可选] 商品类型
  "extra_params": {               // [可选] 扩展参数 (会透传到回调)
    "coupon_id": "C001",
    "referrer": "user_123"
  }
}

Response:

{
  "code": 200,
  "message": "success",
  "data": {
    "order_sn": "202401170001",   // 系统生成的订单号
    "status": "created",          // 订单状态
    "amount": 99.00,
    "expire_at": "2024-01-17T11:30:00Z"  // 订单过期时间
  }
}

---

1.2 发起支付 (收银台)

用户选择支付方式后，获取支付参数。

POST /api/payment/checkout
Content-Type: application/json
Authorization: Bearer {token}

Request Body:

{
  "order_sn": "202401170001",     // [必填] 订单号
  "gateway": "wechat_jsapi",      // [必填] 支付网关 (见下方枚举)
  "return_url": "https://...",    // [可选] 支付成功后跳转地址
  "openid": "oXxx...",            // [条件] 微信JSAPI必填
  "coin_amount": 0                // [可选] 使用虚拟币抵扣金额
}

Gateway 支付网关枚举:

Gateway	说明	返回类型
alipay_web	支付宝PC网页	url (跳转)
alipay_wap	支付宝H5	url (跳转)
alipay_qr	支付宝扫码	qrcode
wechat_native	微信扫码	qrcode
wechat_jsapi	微信公众号/小程序	json (SDK参数)
wechat_h5	微信H5	url (跳转)
wechat_app	微信APP	json (SDK参数)
paypal	PayPal	url (跳转)
stripe	Stripe	url (Checkout Session)
usdt	USDT-TRC20	address (钱包地址)
coin	纯虚拟币支付	direct (直接完成)

Response:

{
  "code": 200,
  "message": "success",
  "data": {
    "trade_sn": "T20240117100001",  // 交易流水号
    "type": "qrcode",               // 响应类型: url/qrcode/json/address/direct
    "payload": "weixin://wxpay/...",// 支付数据 (根据type不同)
    "expiration": 1800,             // 过期时间 (秒)
    "amount": 99.00,                // 实际支付金额 (扣除抵扣后)
    "coin_deducted": 0              // 虚拟币抵扣金额
  }
}

不同 type 的 payload 格式:

// type: "url" - 跳转链接
payload: "https://openapi.alipay.com/gateway.do?..."

// type: "qrcode" - 二维码内容
payload: "weixin://wxpay/bizpayurl?pr=xxx"

// type: "json" - SDK调起参数 (微信JSAPI)
payload: {
  "appId": "wx...",
  "timeStamp": "1705470600",
  "nonceStr": "xxx",
  "package": "prepay_id=wx...",
  "signType": "RSA",
  "paySign": "xxx"
}

// type: "address" - 加密货币地址
payload: {
  "address": "TXxx...",
  "amount_usdt": 13.88,
  "memo": "202401170001"
}

// type: "direct" - 直接完成 (纯虚拟币支付)
payload: { "status": "paid" }

---

1.3 查询订单状态

前端轮询使用，判断支付是否完成。

GET /api/payment/status/{order_sn}
Authorization: Bearer {token}

Response:

{
  "code": 200,
  "message": "success",
  "data": {
    "order_sn": "202401170001",
    "status": "paid",              // created/paying/paid/closed/refunded
    "paid_amount": 99.00,
    "paid_at": "2024-01-17T10:05:00Z",
    "payment_method": "wechat_jsapi",
    "trade_sn": "T20240117100001"
  }
}

订单状态机:

created → paying → paid → (refunded)
    ↓        ↓
  closed   closed

---

1.4 关闭订单

主动关闭未支付的订单。

POST /api/payment/close/{order_sn}
Authorization: Bearer {token}

Response:

{
  "code": 200,
  "message": "success",
  "data": {
    "order_sn": "202401170001",
    "status": "closed",
    "closed_at": "2024-01-17T10:10:00Z"
  }
}

---

2. 回调通知接口 (Webhook)

2.1 统一回调入口

接收第三方支付平台的异步通知。

POST /api/payment/notify/{gateway}

Path Params:

• gateway: alipay / wechat / paypal / stripe / nowpayments

处理逻辑:

1. 根据 gateway 加载对应驱动
2. 验签 (Verify Signature)
3. 幂等性检查 (防重复处理)
4. 更新订单状态
5. 触发业务回调 (发货/开通权限等)
6. 返回平台所需响应

返回格式:

# 支付宝
success

# 微信
<xml><return_code><![CDATA[SUCCESS]]></return_code><return_msg><![CDATA[OK]]></return_msg></xml>

# Stripe
HTTP 200 OK

# PayPal
HTTP 200 OK

---

2.2 同步返回 (Return)

用户支付完成后的页面跳转。

GET /api/payment/return/{gateway}

Query Params: 各平台不同，由平台自动附加

处理逻辑:

1. 解析回传参数
2. 验签
3. 重定向到成功页面

---

3. 辅助接口

3.1 获取可用支付方式

GET /api/payment/methods

Response:

{
  "code": 200,
  "data": {
    "methods": [
      {
        "gateway": "wechat_jsapi",
        "name": "微信支付",
        "icon": "/icons/wechat.png",
        "enabled": true,
        "available": true  // 当前环境是否可用 (如微信内)
      },
      {
        "gateway": "alipay_wap",
        "name": "支付宝",
        "icon": "/icons/alipay.png",
        "enabled": true,
        "available": true
      }
    ]
  }
}

3.2 获取汇率

GET /api/payment/exchange_rate?from=CNY&to=USD

Response:

{
  "code": 200,
  "data": {
    "from": "CNY",
    "to": "USD",
    "rate": 0.139,
    "updated_at": "2024-01-17T00:00:00Z"
  }
}

---

4. 管理接口 (Admin)

4.1 订单列表

GET /api/admin/payment/orders?page=1&limit=20&status=paid
Authorization: Bearer {admin_token}

4.2 交易流水列表

GET /api/admin/payment/trades?page=1&limit=20
Authorization: Bearer {admin_token}

4.3 发起退款

POST /api/admin/payment/refund
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "trade_sn": "T20240117100001",
  "amount": 99.00,
  "reason": "用户申请退款"
}

---

5. 接口签名规范 (可选)

对于安全要求高的场景，可启用接口签名：

// 请求头
X-Sign: sha256(timestamp + nonce + body + secret)
X-Timestamp: 1705470600
X-Nonce: abc123

---

📌 注意事项

1. 金额单位: 所有金额均以元为单位，小数点后2位
2. 时间格式: ISO 8601 格式 YYYY-MM-DDTHH:mm:ssZ
3. 字符编码: UTF-8
4. HTTPS: 生产环境必须使用 HTTPS
5. 幂等性: 相同订单号重复请求返回相同结果