vifo
7b2f3d77ca
- 新增 backend/design/支付模块架构概览.md - 新增 backend/design/支付模块数据库设计.md (21张表 DDL) - 新增 backend/design/支付模块接口设计.md - git.dev.vifo.cc → git.vifo.cc 全局替换
253 lines
7.3 KiB
Markdown
253 lines
7.3 KiB
Markdown
# 支付模块接口设计
|
||
|
||
> **来源**: `~/rui/支付模块架构设计.md` v1.0
|
||
> **创建日期**: 2026-06-08
|
||
> **模块**: rui-payment
|
||
|
||
---
|
||
|
||
## 一、接口分层
|
||
|
||
| 层级 | 路径前缀 | 认证 | 说明 |
|
||
|------|---------|------|------|
|
||
| 对外接口 | `/payment/open/**` | 需认证 | 商户/业务系统调用 |
|
||
| 对外入口 | `/payment/entry/**` | 免认证 | 收银台、扫码支付 |
|
||
| 第三方回调 | `/payment/notify/**` | 免认证 | 支付/退款异步通知 |
|
||
| 内部接口 | `/payment/inner/**` | @Inner | 微服务间调用 |
|
||
|
||
---
|
||
|
||
## 二、对外接口（需认证）
|
||
|
||
### 2.1 支付交易 `/payment/open/trade`
|
||
|
||
#### 统一下单 `POST /payment/open/trade/pay`
|
||
|
||
```java
|
||
// 请求
|
||
{
|
||
"channel": "alipay", // PayChannel 枚举
|
||
"payType": "app", // PayType 枚举
|
||
"merchantOrderNo": "BIZ2026060801", // 业务订单号
|
||
"subject": "商品标题",
|
||
"body": "商品描述",
|
||
"amount": 100.00, // BigDecimal，元
|
||
"currency": "CNY",
|
||
"notifyUrl": "https://xxx/notify",
|
||
"returnUrl": "https://xxx/return",
|
||
"clientIp": "127.0.0.1",
|
||
"userId": "oXXXXXXXX" // 微信 JSAPI 需要 openid
|
||
}
|
||
|
||
// 响应
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"success": true,
|
||
"channelOrderNo": null,
|
||
"payParams": { // 支付宝 APP
|
||
"orderInfo": "alipay_sdk=..."
|
||
},
|
||
// 或 "payUrl": "<form>...</form>", // 支付宝 H5/PC
|
||
// 或 "payQrCode": "weixin://...", // 微信 Native
|
||
// 或 "payParams": {"prepayId": "..."} // 微信 JSAPI
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 统一执行入口 `POST /payment/open/trade/execute`
|
||
|
||
支持所有渠道和动作的通用入口。
|
||
|
||
```java
|
||
// 请求
|
||
{
|
||
"channel": "alipay",
|
||
"action": "query",
|
||
"merchantOrderNo": "PAY20260608001"
|
||
}
|
||
|
||
// 响应 — 查询示例
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"success": true,
|
||
"channelOrderNo": "20260608...",
|
||
"payParams": {
|
||
"tradeStatus": "TRADE_SUCCESS",
|
||
"totalAmount": "100.00"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> 详细的 PayRequest/PayResponse 字段说明和每个 Action 的请求/返回示例见 `rui-payment-provider/API.md`。
|
||
|
||
### 2.2 退款 `/payment/open/refund`
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/payment/open/refund/apply` | POST | 申请退款 |
|
||
| `/payment/open/refund/{refundNo}` | GET | 查询退款单 |
|
||
|
||
#### 申请退款 `POST /payment/open/refund/apply`
|
||
|
||
```java
|
||
// 请求 PayRefundApplyRequest
|
||
{
|
||
"orderNo": "PAY20260608001",
|
||
"refundAmount": 50.00,
|
||
"refundReason": "用户申请退款",
|
||
"notifyUrl": "https://xxx/refund_notify"
|
||
}
|
||
|
||
// 响应 PayRefundVO
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"refundNo": "REF20260608001",
|
||
"orderNo": "PAY20260608001",
|
||
"refundAmount": 50.00,
|
||
"refundStatus": 0, // 0:退款中 1:退款成功 2:退款失败
|
||
"channelRefundNo": null
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.3 分账 `/payment/open/split`
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/payment/open/split/create` | POST | 创建分账订单 |
|
||
| `/payment/open/split/{splitNo}` | GET | 查询分账订单 |
|
||
| `/payment/open/split/execute/{splitNo}` | POST | 执行分账（手动触发） |
|
||
| `/payment/open/split/return/{splitNo}` | POST | 回退分账 |
|
||
|
||
#### 创建分账订单 `POST /payment/open/split/create`
|
||
|
||
```java
|
||
// 请求 SplitOrderCreateRequest
|
||
{
|
||
"orderNo": "PAY20260608001",
|
||
"splitReceivers": [
|
||
{
|
||
"receiverId": 1,
|
||
"receiverType": 1,
|
||
"receiverName": "商户A",
|
||
"amount": 30.00,
|
||
"rate": 0.30
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 2.4 商户进件 `/payment/open/merchant`
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/payment/open/merchant/apply` | POST | 提交商户入驻申请 |
|
||
| `/payment/open/merchant/{merchantNo}` | GET | 查询商户信息 |
|
||
| `/payment/open/merchant/{merchantNo}` | PUT | 更新商户信息 |
|
||
| `/payment/open/merchant/qualification/upload` | POST | 提交资质材料 |
|
||
| `/payment/open/merchant/qualification/{merchantNo}` | GET | 查询资质列表 |
|
||
| `/payment/open/merchant/audit/{merchantNo}` | GET | 查询审核记录 |
|
||
| `/payment/open/merchant/channel/{merchantNo}` | GET | 查询渠道配置 |
|
||
| `/payment/open/merchant/channel/apply` | POST | 申请渠道开通 |
|
||
| `/payment/open/merchant/settle/{merchantNo}` | GET | 查询结算配置 |
|
||
| `/payment/open/merchant/settle/{merchantNo}` | PUT | 更新结算配置 |
|
||
|
||
---
|
||
|
||
## 三、对外入口（免认证）
|
||
|
||
### `/payment/entry`
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/payment/entry/cashier/{orderNo}` | GET | 收银台页面（H5） |
|
||
| `/payment/entry/scan` | POST | 扫码支付 |
|
||
|
||
---
|
||
|
||
## 四、第三方回调（免认证）
|
||
|
||
### `/payment/notify`
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/payment/notify/alipay` | POST | 支付宝支付回调 |
|
||
| `/payment/notify/wechat_pay` | POST | 微信支付回调（JSON body） |
|
||
| `/payment/notify/unionpay` | POST | 银联支付回调 |
|
||
| `/payment/notify/alipay/refund` | POST | 支付宝退款回调 |
|
||
| `/payment/notify/wechat_pay/refund` | POST | 微信退款回调（JSON body） |
|
||
|
||
#### 支付宝回调
|
||
|
||
```
|
||
POST /payment/notify/alipay
|
||
Content-Type: application/x-www-form-urlencoded
|
||
|
||
out_trade_no=PAY20260608001&trade_no=20260608...&trade_status=TRADE_SUCCESS&total_amount=100.00&...
|
||
```
|
||
|
||
- 返回纯文本 `"success"` 表示成功，`"fail"` 表示失败
|
||
|
||
#### 微信回调
|
||
|
||
```
|
||
POST /payment/notify/wechat_pay
|
||
Content-Type: application/json
|
||
|
||
{"id":"xxx","create_time":"...","resource_type":"encrypt-resource","event_type":"TRANSACTION.SUCCESS","resource":{...}}
|
||
```
|
||
|
||
- 请求头携带 `Wechatpay-Serial`, `Wechatpay-Nonce`, `Wechatpay-Signature`, `Wechatpay-Timestamp`
|
||
- 返回 JSON `{"code":"SUCCESS","message":"成功"}`
|
||
|
||
---
|
||
|
||
## 五、内部接口（@Inner）
|
||
|
||
### `/payment/inner`
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/payment/inner/order/status/{orderNo}` | GET | 查询支付状态 |
|
||
| `/payment/inner/order/biz/{bizOrderNo}` | GET | 根据业务订单号查询 |
|
||
| `/payment/inner/order/create` | POST | 创建支付订单（内部调用） |
|
||
|
||
---
|
||
|
||
## 六、管理后台接口
|
||
|
||
### 6.1 支付渠道管理 `/payment/admin/channel`
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/payment/admin/channel/list` | GET | 渠道列表 |
|
||
| `/payment/admin/channel/{id}` | GET | 渠道详情 |
|
||
| `/payment/admin/channel` | POST | 新增渠道 |
|
||
| `/payment/admin/channel/{id}` | PUT | 修改渠道 |
|
||
| `/payment/admin/channel/{id}/enable` | PUT | 启用渠道 |
|
||
| `/payment/admin/channel/{id}/disable` | PUT | 停用渠道 |
|
||
|
||
### 6.2 代理商管理 `/payment/admin/agent`
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/payment/admin/agent/list` | GET | 代理商列表 |
|
||
| `/payment/admin/agent/{id}` | GET | 代理商详情 |
|
||
| `/payment/admin/agent` | POST | 新增代理商 |
|
||
| `/payment/admin/agent/{id}` | PUT | 修改代理商 |
|
||
| `/payment/admin/agent/{id}/commission` | GET | 佣金记录 |
|
||
| `/payment/admin/agent/{id}/settlement` | GET | 结算记录 |
|
||
|
||
### 6.3 结算管理 `/payment/admin/settle`
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/payment/admin/settle/list` | GET | 结算单列表 |
|
||
| `/payment/admin/settle/{id}` | GET | 结算单详情 |
|
||
| `/payment/admin/settle/generate` | POST | 生成结算单 |
|
||
| `/payment/admin/settle/{id}/confirm` | POST | 确认结算 |
|