支付设置 - 接口对接文档

一、功能说明

• 支付设置共 4 项：**默认:0**、**支付1:1**、**支付2:2**、**支付3:3**（冒号后为参数 param）。
• 管理后台可**拖拽排序**，排序后每项的 param 按新顺序自动变为 0、1、2、3。
• 管理后台可对每项**开启/关闭**，H5 仅能查询到已开启的项。

---

二、通用说明

2.1 基础地址

• 管理后台接口前缀：/admin/payOption/
• H5 接口前缀：/api/site/

（实际请求需加上项目部署的域名与上下文路径，例如：https://your-domain.com/admin/payOption/list.do）

2.2 统一响应结构

所有接口均返回 ServerResponse 结构：

字段	类型	说明
status	int	状态码：0 成功，非 0 失败
msg	string	提示信息，可为空
data	object	业务数据，可为 null

状态码约定：

• 0：成功
• 1：业务错误（见 msg）
• 2：参数错误
• 10：需要登录（管理后台接口未登录时）

---

三、管理后台接口（需登录）

3.1 支付设置列表

获取全部 4 项（含已关闭），按当前排序，用于列表展示与拖拽。

请求

• URL： GET 或 POST /admin/payOption/list.do
• 请求参数： 无

响应示例

{
  "status": 0,
  "msg": null,
  "data": [
    {
      "id": 1,
      "name": "默认",
      "param": 0,
      "sortOrder": 0,
      "enabled": 1
    },
    {
      "id": 2,
      "name": "支付1",
      "param": 1,
      "sortOrder": 1,
      "enabled": 1
    },
    {
      "id": 3,
      "name": "支付2",
      "param": 2,
      "sortOrder": 2,
      "enabled": 0
    },
    {
      "id": 4,
      "name": "支付3",
      "param": 3,
      "sortOrder": 3,
      "enabled": 1
    }
  ]
}

字段	类型	说明
id	int	主键
name	string	显示名称：默认/支付1/支付2/支付3
param	int	参数 0/1/2/3，随排序变动
sortOrder	int	排序序号，越小越靠前
enabled	int	1 开启，0 关闭

---

3.2 拖拽排序

根据新顺序更新每项的 param 与 sort_order（第 1 个 id 对应 param=0，第 2 个对应 param=1，以此类推）。

请求

• URL： POST /admin/payOption/updateSort.do
• Content-Type： application/json
• 请求体： 新顺序下的 id 数组，例如把「支付3」拖到第一位则传：[4, 1, 2, 3]

请求体示例

[4, 1, 2, 3]

成功响应示例

{
  "status": 0,
  "msg": "排序已更新",
  "data": null
}

失败示例（如未传或空数组）

{
  "status": 1,
  "msg": "排序数据不能为空",
  "data": null
}

---

3.3 开启/关闭

请求

• URL： GET 或 POST /admin/payOption/setEnabled.do
• 请求参数：

参数名	类型	必填	说明
id	int	是	支付项 id
enabled	int	是	1=开启，0=关闭

请求示例

GET /admin/payOption/setEnabled.do?id=3&enabled=0

成功响应示例

{
  "status": 0,
  "msg": "已关闭",
  "data": null
}

或

{
  "status": 0,
  "msg": "已开启",
  "data": null
}

失败示例（参数错误）

{
  "status": 1,
  "msg": "enabled 只能为 0 或 1",
  "data": null
}

---

四、H5 接口（无需登录）

4.1 查询支付设置列表（仅已开启）

H5 端用此接口获取当前**已开启**的支付项，按 sort_order 排序。可用于展示「默认:0」「支付1:1」等选项。

请求

• URL： GET 或 POST /api/site/getPayOptionList.do
• 请求参数： 无

响应示例

{
  "status": 0,
  "msg": null,
  "data": [
    {
      "id": 1,
      "name": "默认",
      "param": 0,
      "sortOrder": 0,
      "enabled": 1
    },
    {
      "id": 2,
      "name": "支付1",
      "param": 1,
      "sortOrder": 1,
      "enabled": 1
    },
    {
      "id": 4,
      "name": "支付3",
      "param": 3,
      "sortOrder": 3,
      "enabled": 1
    }
  ]
}

说明：若某项在管理后台被关闭，则不会出现在本接口的 data 中。H5 只需根据 name 与 param 展示，如「默认:0」「支付1:1」。

---

五、对接流程简述

端	流程
管理后台	1. 调用 list.do 展示列表 → 2. 拖拽后按新顺序把 id 数组调 updateSort.do → 3. 开关调 setEnabled.do
H5	调用 getPayOptionList.do 获取已开启的支付项，按返回顺序展示（name + param）

---

六、数据表与初始化

表名：site_pay_option。建表及初始化语句见同目录下 site_pay_option.sql。首次部署需执行该 SQL。