meal_manager/jeesharp-business/business-pay/特约商户进件-结算与注销-后台接口文档.md

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

模块：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 }

---

二、修改结算账户

微信文档：修改结算账户

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

---

三、商户注销

微信文档：商户注销（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	新增修改结算账户、商户注销接口文档