# 支付模块接口设计

> **来源**: `~/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 | 确认结算 |