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

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

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

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

1.1 创建订单

• URL: POST /api/payment/create_order
• Description: 业务系统通知支付模块创建一个待支付订单。
• Request Body:

  {
    "user_id": "u1001",           // 用户ID
    "title": "VIP Membership",    // 订单标题
    "amount": 99.00,              // 金额 (法币单位: 元 / 美元)
    "currency": "CNY",            // 币种: CNY, USD
    "product_id": "vip_01",       // 商品ID
    "extra_params": {}            // 扩展参数
  }
  

• Response:

  {
    "code": 200,
    "data": {
      "order_sn": "202310270001", // 支付系统生成的唯一订单号
      "status": "created"
    }
  }
  

1.2 发起支付 (收银台)

• URL: POST /api/payment/checkout
• Description: 用户选择支付方式后，获取支付参数。
• Request Body:

  {
    "order_sn": "202310270001",
    "gateway": "alipay_qr",       // 支付方式: alipay_qr, wechat_jsapi, paypal, usdt, stripe
    "return_url": "https://...",  // 支付成功后前端跳转地址
    "openid": "..."               // 微信JSAPI支付必填
  }
  

• Response:

  {
    "code": 200,
    "data": {
      "type": "url",              // url (跳转), qrcode (扫码), json (SDK参数), address (USDT)
      "payload": "https://...",   // 具体内容
      "expiration": 1800          // 过期时间(秒)
    }
  }
  

1.3 查询订单状态

• URL: GET /api/payment/status/{order_sn}
• Description: 前端轮询使用。
• Response:

  {
    "code": 200,
    "data": {
      "status": "paid",           // created, paying, paid, closed
      "paid_amount": 99.00,
      "paid_at": "2023-10-27 10:00:00"
    }
  }
  

---

2. 回调通知接口 (Webhook)

2.1 统一回调入口

• URL: POST /api/payment/notify/{gateway}
• Description: 接收第三方支付平台的异步通知。
• Path Params:
  • gateway: alipay, wechat, paypal, stripe, nowpayments
• Logic:
  1. 根据 gateway 加载对应驱动。
  2. 验签 (Verify Signature)。
  3. 幂等性检查 (Idempotency Check)。
  4. 更新订单状态。
  5. 返回平台所需的响应字符串 (e.g. success, 200 OK).

---

3. 辅助接口

3.1 获取汇率

• URL: GET /api/payment/exchange_rate
• Params: from=USD&to=CNY
• Response: {"rate": 7.21}