# 特约商户进件 · 后台接口文档（结算修改 / 商户注销）

> **模块**：business-pay  
> **基础路径**：`/manager/business/pay/paySubMerchantApplyment/v1`  
> **说明**：结算修改与商户注销挂在进件 Controller 下，与进件主流程独立，不修改进件草稿。  
> **更新日期**：2026-06-15

---

## 一、接口规范

| 项目 | 规范 |
|------|------|
| Content-Type | `application/json;charset=UTF-8` |
| Authorization | `Bearer {token}` |
| 响应结构 | `{ code, msg, data, requestId }` |

---

## 二、修改结算账户

微信文档：[修改结算账户](https://pay.weixin.qq.com/doc/v3/partner/4012711988)

### 2.1 查询当前结算账户

- **URL**：`GET .../settlement/current?applymentId={进件主键}`
- **权限**：`manager:business:pay:paySubMerchantApplyment:settlementCurrent`

### 2.2 提交修改结算账户

- **URL**：`POST .../settlement/modify`
- **权限**：`manager:business:pay:paySubMerchantApplyment:settlementModify`

**请求体**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| applymentId | String | 是 | 进件主表 ID |
| accountType | String | 是 | `ACCOUNT_TYPE_BUSINESS` / `ACCOUNT_TYPE_PRIVATE` |
| accountBank | String | 是 | 开户银行 |
| accountNumber | String | 是 | 银行账号（明文，服务端加密提交微信） |
| accountName | String | 是 | 开户名称 |
| bankBranchId | String | 否 | 联行号（其他银行时与 bankName 至少填一项） |
| bankName | String | 否 | 开户银行全称 |
| bankAddressCode | String | 否 | 开户银行省市编码 |

**业务规则**：须已有 `subMchId`；商户已注销（`SUB_MCH_CANCELLED`）不可提交；每日每进件最多 5 次；不可存在审核中申请。

### 2.3 同步修改审核状态

- **URL**：`GET .../settlement/modify/syncStatus?modifyId={记录ID}`
- **权限**：`manager:business:pay:paySubMerchantApplyment:settlementSync`

### 2.4 修改历史列表

- **URL**：`GET .../settlement/modify/list?applymentId={进件主键}`
- **权限**：`manager:business:pay:paySubMerchantApplyment:settlementList`

---

## 三、商户注销

微信文档：[商户注销](https://pay.weixin.qq.com/doc/v3/partner/4012711989)（apply-cancel-withdraw）

### 3.1 注销资格校验

- **URL**：`GET .../cancel/validate?applymentId={进件主键}`
- **权限**：`manager:business:pay:paySubMerchantApplyment:cancelValidate`

**响应 data 主要字段**：

| 字段 | 说明 |
|------|------|
| subMchId | 特约商户号 |
| merchantState | `NORMAL` / `HAS_BEEN_CANCELLED` |
| validateResult | `ALLOW_CANCEL_WITHDRAW` / `NOT_ALLOW_CANCEL_WITHDRAW` |
| blockReasons | 不可注销原因列表（type、description） |
| accountInfo | 账户余额（outAccountType、amount，单位分） |

### 3.2 提交商户注销

- **URL**：`POST .../cancel/submit`
- **权限**：`manager:business:pay:paySubMerchantApplyment:cancelSubmit`

**请求体**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| applymentId | String | 是 | 进件主表 ID |
| withdraw | String | 是 | `NOT_APPLY_WITHDRAW` 仅注销；`APPLY_WITHDRAW` 注销并提现 |
| accountType | String | 提现时必填 | 同结算修改 |
| accountBank | String | 提现时必填 | 开户银行 |
| accountNumber | String | 提现时必填 | 银行账号 |
| accountName | String | 提现时必填 | 开户名称 |
| bankBranchId / bankName | String | 否 | 其他银行规则同结算修改 |

**业务规则**：提交前自动调用资格校验；不可存在进行中注销单；不可重复注销（进件状态已为 `SUB_MCH_CANCELLED`）。

### 3.3 同步注销状态

- **URL**：`GET .../cancel/syncStatus?cancelId={注销记录ID}`
- **权限**：`manager:business:pay:paySubMerchantApplyment:cancelSync`

当微信 `cancel_state=FINISH` 时，服务端回写进件主表 `apply_status=SUB_MCH_CANCELLED`。

### 3.4 平台代商户确认注销

- **URL**：`POST .../cancel/confirm`
- **权限**：`manager:business:pay:paySubMerchantApplyment:cancelConfirm`

**请求体**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cancelId | String | 是 | 本地注销记录 ID |
| cancelContractVersion | String | 是 | 注销协议版本，如 `V20241213` |

仅 `cancel_state=WAITING_MERCHANT_CONFIRM` 时可调用。

### 3.5 注销历史列表

- **URL**：`GET .../cancel/list?applymentId={进件主键}`
- **权限**：`manager:business:pay:paySubMerchantApplyment:cancelList`

---

## 四、枚举速查

### 4.1 注销方式 withdraw

| 值 | 说明 |
|----|------|
| NOT_APPLY_WITHDRAW | 仅注销，不提现 |
| APPLY_WITHDRAW | 注销并提取余额 |

### 4.2 注销状态 cancel_state

| 值 | 说明 |
|----|------|
| ACCEPTED | 已受理 |
| REVIEWING | 审核中 |
| REJECTED | 审批驳回（终态，可重新发起） |
| WAITING_MERCHANT_CONFIRM | 待商户确认 |
| CANCELED | 已注销（流程中） |
| FINISH | 注销完成（终态，回写进件为 SUB_MCH_CANCELLED） |

### 4.3 注销资格校验 validate_result

对应 Java：`PaySubMerchantCancelValidateResultEnum`；前端：`cancelOptions.ts` → `CANCEL_VALIDATE_RESULT`。

| 值 | 说明 |
|----|------|
| ALLOW_CANCEL_WITHDRAW | 可发起注销 |
| NOT_ALLOW_CANCEL_WITHDRAW | 不可发起注销 |

### 4.4 进件状态（注销相关）

| 值 | 说明 |
|----|------|
| SUB_MCH_CANCELLED | 商户已注销（注销 FINISH 后回写） |

---

## 五、权限标识汇总

```
manager:business:pay:paySubMerchantApplyment:settlementCurrent
manager:business:pay:paySubMerchantApplyment:settlementModify
manager:business:pay:paySubMerchantApplyment:settlementSync
manager:business:pay:paySubMerchantApplyment:settlementList
manager:business:pay:paySubMerchantApplyment:cancelValidate
manager:business:pay:paySubMerchantApplyment:cancelSubmit
manager:business:pay:paySubMerchantApplyment:cancelSync
manager:business:pay:paySubMerchantApplyment:cancelConfirm
manager:business:pay:paySubMerchantApplyment:cancelList
```

菜单 SQL：`doc/sql/business-pay/pay_admin_menu.sql` 或增量 `pay_sub_merchant_*_permissions.sql`。

---

## 六、更新日志

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0 | 2026-06-15 | 新增修改结算账户、商户注销接口文档 |