支付方式配置 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 已由后端国际化，可直接用于错误提示。

{
  "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 结算页可用支付方式

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

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

查询参数：

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

响应 data 为数组，每项：

[
  { "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 线下转账收款信息

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 字段：

{
  "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：

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

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

5. 骑手端接口

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

5.1 查询收款方式设置

GET /system/riderFlashPayMethods

响应 data：

{
  "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 保存收款方式

PUT /system/riderFlashPayMethods

请求体：

{
  "methodCodes": ["OFFLINE_TRANSFER"]
}

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

5.3 银行卡管理

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

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

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

[
  {
    "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，修改必传）：

{
  "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 确认收款

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 直接展示，不做本地拼接。

pay-method-config-app-api.md 17 KB تاريخچه خام