## 开始前
开始本场景前，应已完成[开发前准备](../开始接入/开发前准备.md)和[请求与签名](../开始接入/请求与签名.md)，并具备：
- 当前收银设备对应的`terminal_sn`和`terminal_key`。
- 能被公网访问的支付回调地址。
- 可保存商户订单、收钱吧订单号、订单状态和履约状态的数据表。
- 能够在结果未知时查询原订单的后台任务。
## 接口调用时序图
创建商户订单 → 扫描顾客付款码 → **[付款码支付接口](https://open.shouqianba.com/docs/payment/75?category_id=54)** → 非最终状态调用**[查询接口](https://open.shouqianba.com/docs/payment/71?category_id=54)** → **[回调接口](https://open.shouqianba.com/docs/payment/70?category_id=54)**或查询确认成功 → 幂等履约 → 售后需要时调用**[退款接口](https://open.shouqianba.com/docs/payment/72?category_id=54)**。
## 创建商户订单
- 目标：在扫码前建立一笔可追踪的待支付订单。
- 输入来源：商品、应收金额、门店、收银员和当前设备来自商户业务系统。
- 商户系统处理：生成全局唯一的商户订单号，并把订单状态保存为“待支付”。
- 输出用途：该订单号用于发起支付、主动查询、接收回调和后续退款。
- 下一步：收银页面进入扫码状态。
同一笔业务只能使用一个商户订单号。请求超时或结果未知时继续查询这个订单号，不要换号再次扣款。
## 获取顾客付款码
- 目标：读取顾客当前展示的一次性付款凭证。
- 输入来源：扫码枪、摄像头或收银设备读取顾客支付应用中的付款码。
- 商户系统处理：仅在当前支付请求中短暂使用付款码，不写日志、不长期保存、不回显给无关人员。
- 输出用途：作为付款码支付请求的动态支付凭证。
- 下一步：立即提交支付；付款码过期或无法识别时，让顾客重新展示。
## 发起付款码支付
- 目标：用当前商户订单和顾客付款码发起扣款。
- 调用接口：**[付款码支付接口](https://open.shouqianba.com/docs/payment/75?category_id=54)**。
- 输入来源：商户订单号、金额和商品信息来自已保存的商户订单；付款码来自刚才的扫码结果；终端参数来自当前设备的安全配置；回调地址来自服务端配置。
- 签名凭证：使用当前终端的`terminal_sn`和`terminal_key`。
- 输出用途：保存收钱吧订单号、订单状态、流水状态和错误信息。
- 下一步：按同步响应判断最终成功、最终失败或非最终状态。
完整请求字段、格式和长度请直接查看接口文档。
## 处理同步结果
按[交易结果与异常处理](../开始接入/交易结果与异常处理.md)读取响应：
- 明确最终成功：原子更新交易状态，进入履约。
- 明确最终失败：保存失败原因，允许收银员按业务规则重新发起一笔新支付。
- 等待顾客验证、处理中、结果未知、HTTP超时或响应无法解析：保持原订单为“支付中”，进入主动查询。
不能根据HTTP请求已返回、收银端动画或单一消息文本判断支付成功。
## 查询非最终结果
- 目标：确认原付款码支付订单的最终状态，避免重复扣款。
- 调用接口：**[查询接口](https://open.shouqianba.com/docs/payment/71?category_id=54)**。
- 输入来源：使用支付步骤中已经保存的原商户订单号或收钱吧订单号。
- 输出用途：与同步响应和回调共用一套订单状态机。
- 下一步：最终成功则履约；最终失败则结束；仍为非最终状态则按本场景节奏继续查询。
首次同步结果非最终时，每隔3至5秒查询一次，总查询时间控制在40至50秒。达到上限仍无最终结果时，停止自动扣款，把订单标记为“结果未知”并进入人工核实。
## 接收支付回调
- 目标：异步接收订单状态变化。
- 对接接口：**[回调接口](https://open.shouqianba.com/docs/payment/70?category_id=54)**。
- 输入来源：收钱吧向商户配置的公网回调地址发送通知。
- 商户系统处理：读取原始通知、完成验签、通过订单号定位原订单，并幂等更新状态。
- 输出用途：补偿收银页面关闭、网络中断或主动查询未及时取得结果的情况。
- 下一步：数据成功落库后返回`success`；最终成功时只触发一次履约。
回调和查询可能同时到达，二者必须更新同一笔订单，不能各自创建业务记录。
## 完成履约
- 触发条件：服务端已经取得并验证最终支付成功。
- 执行动作：出货、开闸、打印小票、发券或更新会员权益。
- 幂等要求：以商户订单号作为幂等键，同一订单只执行一次成功履约。
- 异常处理：支付已成功但履约失败时，仅重试履约，不能重新发起支付。
## 发起退款
- 目标：对已确认成功的原支付订单发起全额或部分退款。
- 调用接口：**[退款接口](https://open.shouqianba.com/docs/payment/72?category_id=54)**。
- 输入来源：原支付订单标识来自已保存交易；退款金额和原因来自商户售后系统；每次退款使用唯一退款流水号。
- 输出用途：保存退款流水及其状态，并关联原支付订单。
- 下一步：结果非最终或请求超时时查询原退款流水，明确成功后再更新退款结果。
## 完成标准
- [ ] 顾客付款码只在支付链路中安全传递。
- [ ] 同步成功能够完成一次履约。
- [ ] 有密、处理中和请求超时能够查询原订单。
- [ ] 支付回调已验签并支持重复通知。
- [ ] 查询、回调和同步结果共用一个订单状态机。
- [ ] 结果未知时不会更换订单号重复扣款。
- [ ] 支付成功后的退款能够被正确追踪。
收钱吧开放平台