# 支付方式配置 App 接入文档

本文档供用户端 App 和骑手端 App 接入支付方式配置（031）使用，以当前后端实现为准。文档只描述接口契约和业务流程，不包含 App 前端实现代码。商家 PC 端（foodie-store）与平台后台的支付方式管理页面已另行完成，不在本文档范围。

> 更新时间：2026-09-29。本文覆盖 031 全量 App 侧增量：用户端结算页支付方式查询、现金自取/堂食语义、闪送支付方式与确认收款、骑手端收款方式设置与银行卡管理。

当前契约要点：

- 支付方式可用性由后端「平台开关 × 收款方选择 × 就绪度」三层闸门统一判定。App 一律以查询接口的返回渲染可选支付方式，不得本地写死可用性；下单提交未开放的支付方式会被后端拒绝。
- 支付方式按「组代码 methodCode」管理，一个组可对应一个或多个 `payType` 数值；App 对用户展示自己的文案，下单时提交 `payType` 数值。
- 用户端餐饮结算页新增匿名接口 `GET /system/storePayMethods`，替代旧版"按 bankInfo 是否有数据判断线下转账显隐"的做法；`bankInfo` 接口继续负责线下转账的收款信息内容，路径与返回结构不变。
- 现金（payType=4）仅自取（type=1）和堂食（type=2）可用；现金订单创建后直接进入"进行中"（payStatus=1），不经"待付款"。
- 闪送首页与报价响应新增 `payMethods` 列表；下单 `payType` 缺省为现金 4，线下转账为 6；订单视图新增 `paymentStatus`，线下转账单送达后向寄件人展示骑手收款卡。
- 骑手端新增收款方式设置、本人银行卡管理和送达后确认收款三个能力；骑手待抢列表按骑手接受的支付方式过滤订单。

## 1. 功能范围

当前支持：

- 平台按"商家餐饮"和"骑手闪送"两个维度独立开关支付方式；开关关闭的方式对所有相关方不可见、不可用。
- 商家在商家 PC 端勾选自己接受的支付方式（未设置视为全部接受）；本文档的查询接口已折算该选择。
- 线下转账的就绪度按收款方是否有启用银行卡判定；商家与骑手各自维护本人（商家为主账号）银行卡。
- 用户餐饮结算页按门店查询可用支付方式，含就绪度标记；现金仅出现在自取/堂食场景。
- 餐饮现金自取/堂食下单：商家接受现金时可用，订单创建后 payStatus=1，直接进入进行中。
- 闪送下单选择现金（默认）或线下转账；骑手待抢列表按骑手接受的支付方式过滤；送达后骑手确认收款，寄件人在送达后看到骑手收款卡用于线下转账结清。

当前不包含：在线支付新渠道接入、退款、找零、开票；这些仍走各自既有流程。

## 2. 通用约定

### 2.1 基础地址和请求头

接口路径均为相对路径，实际请求地址为 `{baseUrl}{接口路径}`。

| 请求头 | 必填 | 说明 |
|---|---:|---|
| `token` | 标注"登录"的接口必填 | App 登录后取得的 JWT。不要放在 `Authorization` 中 |
| `Content-Type` | POST/PUT JSON 接口必填 | `application/json` |

用户身份、骑手身份、商家身份均由 `token` 解析，请求体中不提交 `userId`。标注"匿名"的接口不需要 `token`，携带了也会被忽略。

### 2.2 统一响应

与闪送接口一致：App 必须以响应体 `code` 判断业务是否成功，不能只依赖 HTTP 状态码。`msg` 已由后端国际化，可直接用于错误提示。

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}
```

业务失败时 `code=500`，`msg` 为国际化文案；登录失效时 `code=401`。

## 3. 支付方式枚举

### 3.1 组代码与 payType 对照

| 组代码 `methodCode` | `payType` | 含义 | 说明 |
|---|---|---|---|
| `COD` | `1` | 货到付款 | 默认开放，无额外就绪度要求 |
| `CARD_OMG` | `2` / `5` | 信用卡 / Apple Pay | 同组同开同关，就绪度一致；接口按 payType 展开为两项 |
| `LINE_PAY` | `3` | LINE Pay | — |
| `CASH` | `4` | 现金 | 仅商家餐饮维度；且仅自取/堂食场景返回与可用 |
| `OFFLINE_TRANSFER` | `6` | 线下转账 | 就绪度取决于收款方启用银行卡 |

下单接口提交的是 `payType` 数值字符串；查询接口返回的是 `methodCode` + `payType` 成对出现，App 按 `payType` 回传。

### 3.2 各端可用集合

| 维度 | 可出现的组 | 说明 |
|---|---|---|
| 商家餐饮（用户结算页） | `COD`、`CARD_OMG`、`LINE_PAY`、`OFFLINE_TRANSFER`、`CASH` | `CASH` 仅当查询参数 `type` 为 1 或 2 且商家接受时出现 |
| 骑手闪送（首页/报价、骑手设置） | `COD`、`LINE_PAY`、`OFFLINE_TRANSFER` | 闪送款项直达骑手，无线上卡支付组；现金为缺省支付，不在列表中 |

最终可用 = 平台开关（关闭的组不返回）∩ 收款方勾选（未设置视为全部）∩ 就绪度。App 只按接口返回渲染。

### 3.3 闪送订单 `paymentStatus`

| 值 | 含义 |
|---|---|
| `0` | 骑手尚未确认收到款项（默认） |
| `1` | 骑手已确认收到款项 |

`paymentStatus` 出现在闪送用户订单列表/详情和骑手订单列表/详情中。它只表示骑手侧的线下收款确认，不发起任何在线支付或扣款。

## 4. 用户端接口

### 4.1 结算页可用支付方式

```http
GET /system/storePayMethods?storeId={storeId}&type={type}
```

匿名接口，无需 `token`。App 进入餐饮结算页时调用，按返回渲染支付方式列表。

查询参数：

| 参数 | 必填 | 说明 |
|---|---:|---|
| `storeId` | 是 | 门店 ID；门店不存在时返回空数组 |
| `type` | 否 | 订单类型：`1` 自取、`2` 堂食、`0` 外送 |

响应 `data` 为数组，每项：

```json
[
  { "methodCode": "COD", "payType": "1", "ready": true },
  { "methodCode": "CARD_OMG", "payType": "2", "ready": true },
  { "methodCode": "CARD_OMG", "payType": "5", "ready": true },
  { "methodCode": "OFFLINE_TRANSFER", "payType": "6", "ready": false }
]
```

| 字段 | 类型 | 说明 |
|---|---|---|
| `methodCode` | string | 组代码，取值见 3.1 |
| `payType` | string | 下单时提交的支付方式数值 |
| `ready` | boolean | 就绪度；`false` 的项 App 不得渲染（如商家未启用银行卡的线下转账） |

规则：

- `type=1` 或 `2` 且商家接受现金（勾选含 `CASH` 或未设置）时，返回中追加 `{ "methodCode": "CASH", "payType": "4", "ready": true }`。
- `type=0`（外送）或不传 `type` 时不返回现金项。老版本 App 不传 `type`，行为与旧接口完全一致。
- 用户切换自取/堂食/外送后必须重新调用本接口刷新列表。
- 线下转账 `ready=false` 时不渲染；`ready=true` 时渲染选项，但收款账户信息仍从 4.3 的 `bankInfo` 获取。

### 4.2 餐饮下单提交支付方式

下单仍走既有 `UserOrderController.createOrder`，支付方式字段的增量语义：

- 提交的 `payType` 必须是 4.1 返回过的值（或老版本既有的到付/卡/LINE Pay 值）；提交后端判定不可用的方式会返回 `code=500`、`msg=该支付方式当前不可用，请更换支付方式`，订单不会创建。
- 现金（`payType=4`）仅当订单 `type=1` 自取或 `2` 堂食且商家接受时可用；外送订单直传 `4` 一律被拒绝。
- 现金订单创建成功后 `payStatus=1`（同到付的线下收款语义），订单直接出现在"进行中"，不会出现在"待付款"页签。
- 现金订单的取消、售后行为与到付订单一致。

### 4.3 线下转账收款信息

```http
GET /chanting/store/bankInfo?id={storeId}
```

匿名接口，路径、参数与返回结构保持不变。用户选择线下转账后，用 `data` 中的 `bankAccountName`、`bankName`、`bankAccountNo` 三字段展示收款信息；商家无启用银行卡或线下转账未开放时 `data=null`，App 隐藏收款信息区。

本接口只管"转账信息内容"，选项显隐一律以 4.1 的 `ready` 为准，不要再按 `bankInfo` 是否有数据决定支付方式选项的显隐。

### 4.4 闪送支付方式（既有接口增量）

闪送首页 `GET /system/flashDelivery/home` 与报价 `POST /system/flashDelivery/quote` 的响应新增 `payMethods` 字段：

```json
{
  "payMethods": [
    { "methodCode": "OFFLINE_TRANSFER", "payType": "6", "ready": true }
  ]
}
```

- 列表是现金之外的可选支付方式；现金（`payType=4`）为缺省值，恒可用，不在列表中。
- `ready=false` 的项不渲染（如当前没有启用银行卡的骑手群体时，平台仍开放线下转账，但就绪度需按返回处理；用户下单时以列表返回为准）。
- App 按 `payMethods` 渲染选项，不要本地写死只有"现金/线下转账"两项；未来平台开放其他闪送支付方式时无需改版。

创建闪送订单 `POST /system/flashDelivery/orders` 的请求体新增可选字段 `payType`：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `payType` | string | 否 | 支付方式：缺省 `4` 现金；`6` 线下转账。闪送款项直达骑手，下单后锁定，不可修改 |

提交列表之外的值会被拒绝：`msg=该支付方式当前不可用，请更换支付方式`。

闪送订单详情与列表新增 `paymentStatus`（见 3.3）。寄件人视角的订单详情，在线下转账单状态到达 `DELIVERED` 或 `COMPLETED` 后，额外返回 `riderBankCard`：

```json
{
  "riderBankCard": {
    "bankName": "台湾银行",
    "accountNo": "123456789012",
    "accountName": "陈骑手"
  }
}
```

- 仅寄件人视角、且订单 `payType=6`、状态为已送达或已完成时返回；其他情况该字段为 `null`，App 不展示。
- 该卡片是中单骑手的启用收款卡，用于寄件人线下转账结清；转账完成由骑手确认（见 5.5），确认后 `paymentStatus=1`。

## 5. 骑手端接口

所有接口均要求骑手登录 `token`，且账号 `userType` 必须为 `2`；非骑手调用按无权限处理（`msg=用户已停用`）。

### 5.1 查询收款方式设置

```http
GET /system/riderFlashPayMethods
```

响应 `data`：

```json
{
  "available": [
    { "methodCode": "COD", "payType": "1", "ready": true },
    { "methodCode": "LINE_PAY", "payType": "3", "ready": true },
    { "methodCode": "OFFLINE_TRANSFER", "payType": "6", "ready": false }
  ],
  "selected": ["OFFLINE_TRANSFER"]
}
```

| 字段 | 说明 |
|---|---|
| `available` | 平台闪送维度开放的支付方式全集，附就绪度；线下转账的 `ready` 表示骑手本人当前是否有启用银行卡 |
| `selected` | 骑手当前勾选；空数组表示未设置，语义为"接受全部可用方式" |

骑手设置页按 `available` 渲染勾选列表，`ready=false` 的项可展示但应标注未就绪原因（如"请先添加银行卡"）。

### 5.2 保存收款方式

```http
PUT /system/riderFlashPayMethods
```

请求体：

```json
{
  "methodCodes": ["OFFLINE_TRANSFER"]
}
```

- `methodCodes` 内的每个值必须是 5.1 `available` 中出现过的 `methodCode`，否则返回 `msg=支付方式设置参数不合法`。
- 空数组或传 `[]` 表示清空选择，回落"接受平台开放的全部方式"。
- 保存成功无 `data`。保存后立即影响本人待抢列表的订单过滤。

### 5.3 银行卡管理

骑手本人收款卡的新增、维护。线下转账就绪度取决于是否存在 `isActive=1` 的卡。

```http
GET    /system/bankCard
POST   /system/bankCard
PUT    /system/bankCard
DELETE /system/bankCard/{id}
PUT    /system/bankCard/activate/{id}
```

查询列表响应 `data` 为数组，启用卡排在前：

```json
[
  {
    "id": 3,
    "userId": 20001,
    "bankName": "台湾银行",
    "accountNo": "123456789012",
    "accountName": "陈骑手",
    "isActive": 1,
    "createTime": "2026-09-20 10:00:00",
    "updateTime": "2026-09-20 10:00:00"
  }
]
```

新增/修改请求体（新增不传 `id`，修改必传）：

```json
{
  "id": null,
  "bankName": "台湾银行",
  "accountNo": "123456789012",
  "accountName": "陈骑手"
}
```

| 字段 | 必填 | 规则 |
|---|---:|---|
| `bankName` | 是 | 最长 64 字符；必须与平台字典 `taiwan_bank_list` 的银行名称完全一致，否则 `msg=银行名称不合法` |
| `accountNo` | 是 | 最长 64 字符 |
| `accountName` | 是 | 最长 64 字符 |

规则：

- 同一骑手最多 10 张卡，超出返回 `msg=最多只能保存10张银行卡`。
- 第一张卡新增后自动启用；之后新增的卡默认停用，需调用启用接口。
- 启用接口 `PUT /system/bankCard/activate/{id}` 会自动停用原启用卡，保证同一骑手最多一张启用卡；启用后付款方下次查询即看到新卡。
- 删除启用卡后本人回到"无启用卡"状态，线下转账不再就绪。
- 只能操作本人卡；操作他人卡 ID 按无权限处理。
- 骑手订单列表按支付方式过滤后，未启用银行卡且未勾选线下转账的骑手看不到线下转账订单；启用卡并勾选后新订单立即可见。

### 5.4 抢单列表的支付方式过滤（行为说明）

`GET /system/flashDelivery/rider/orders` 的 `newTask` 列表按当前骑手接受的支付方式过滤：

- 现金（`payType=4`）订单对所有人恒可见，不受勾选影响。
- 线下转账订单只对"平台开放 ∩ 本人勾选（或未设置）∩ 本人存在启用银行卡"的骑手可见。
- 骑手列表摘要的 `payType` 字段照常返回；App 可据此在订单卡片上展示"线下转账"标识，提示送达后需向寄件人收款并确认。

### 5.5 确认收款

```http
POST /system/flashDelivery/rider/orders/{id}/confirmPayment
```

无请求体。`{id}` 为订单 ID（路径参数）。

条件与效果：

- 仅本人中单的订单；非本人订单返回 `msg=快送订单不存在或无权访问`。
- 订单状态必须已达 `DELIVERED` 或 `COMPLETED`；未送达时返回 `msg=订单尚未送达，不能确认收款`。
- 成功后订单 `paymentStatus` 0→1，并写入操作日志；状态推进本身不受影响。
- 幂等：`paymentStatus` 已为 1 时重复调用仍返回成功。

App 流程：线下转账单送达后，在订单详情向骑手展示"确认收款"入口（按 `paymentStatus=0` 且状态已送达/已完成显示）；点击确认成功后刷新本地 `paymentStatus`，入口变为已确认状态。现金单同样可以确认，但 App 可按 `payType` 决定是否强调该入口。

## 6. 常见业务错误与处理建议

| `msg` 含义 | 常见原因 | App 处理建议 |
|---|---|---|
| 该支付方式当前不可用，请更换支付方式 | 平台关闭、收款方未勾选、就绪度不满足，或现金用于外送订单 | 重新拉取可用支付方式列表，让用户换选 |
| 支付方式设置参数不合法 | 骑手保存了列表之外的 `methodCode` | 重新拉取 5.1 数据后按返回值提交 |
| 银行卡信息不合法 | 必填缺失、超长或修改时缺 `id` | 返回表单修正 |
| 银行名称不合法 | `bankName` 不在 `taiwan_bank_list` 字典 | 银行名称必须从字典/下拉选择，不允许自由输入 |
| 最多只能保存10张银行卡 | 卡数达上限 | 提示先删除不用的卡 |
| 订单尚未送达，不能确认收款 | 确认收款时订单未到 `DELIVERED` | 隐藏入口，送达后再展示 |
| 快送订单不存在或无权访问 | 确认收款时订单非本人中单或已不存在 | 返回列表并刷新 |
| 用户已停用 | 非骑手调用骑手端接口，或账号状态异常 | 引导重新登录或联系平台 |
| token 已过期 | 登录态失效 | 清理登录态并重新登录 |

## 7. 接入验收清单

- 结算页支付方式列表只按 `GET /system/storePayMethods` 的返回渲染，不本地写死；`ready=false` 的项不渲染。
- 切换自取/堂食/外送时重新查询支付方式列表；现金项仅在自取/堂食出现。
- 线下转账的选项显隐以 `ready` 为准；收款信息仍取自 `bankInfo`，两个接口各司其职。
- 现金订单创建成功后直接按"进行中"展示，不出现"待付款"状态。
- 闪送首页/报价按 `payMethods` 渲染可选支付方式，现金为缺省项；创建订单原样回传所选 `payType`，缺省不传即现金。
- 寄件人仅在线下转账单送达/完成后展示 `riderBankCard` 三要素，其余状态不展示。
- 骑手设置页按 `available` 渲染、按 `selected` 回显；空勾选保存后语义为"接受全部"。
- 骑手银行卡银行名称从字典下拉选择，不允许自由输入；首张卡自动启用、多卡单启用由 activate 接口保证。
- 骑手"确认收款"入口仅在 `paymentStatus=0` 且状态为已送达/已完成时展示；确认成功后刷新为已确认，重复点击不报错。
- 待抢列表对线下转账订单可展示"线下转账"标识，金额文案仍为"订单金额"，不使用"收益"。
- 所有接口以响应体 `code` 判断成功失败；`msg` 直接展示，不做本地拼接。