soul/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: ```json { "user_id": "u1001", // 用户ID "title": "VIP Membership", // 订单标题 "amount": 99.00, // 金额 (法币单位: 元 / 美元) "currency": "CNY", // 币种: CNY, USD "product_id": "vip_01", // 商品ID "extra_params": {} // 扩展参数 } ```
• Response: ```json { "code": 200, "data": { "order_sn": "202310270001", // 支付系统生成的唯一订单号 "status": "created" } } ```

1.2 发起支付 (收银台)

• URL: POST /api/payment/checkout
• Description: 用户选择支付方式后，获取支付参数。
• Request Body: ```json { "order_sn": "202310270001", "gateway": "alipay_qr", // 支付方式: alipay_qr, wechat_jsapi, paypal, usdt, stripe "return_url": "https://...", // 支付成功后前端跳转地址 "openid": "..." // 微信JSAPI支付必填 } ```
• Response: ```json { "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: ```json { "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}