## 开始前

开始本场景前，应已完成[开发前准备](../开始接入/开发前准备.md)和[请求与签名](../开始接入/请求与签名.md)，并具备：

- 当前展示设备对应的终端参数。
- 能创建二维码生成流水和真实支付订单的数据结构。
- 能被公网访问的真实交易回调地址。
- 能根据真实交易标识主动查询订单的后台任务。

## 接口调用时序图

![20260820-093328.png](https://img-hub.wosaimg.com/file/2026/08/20/9da6498809da40dd.png)

准备二维码业务信息 → **[二维码生成接口](https://open.shouqianba.com/docs/payment/100?category_id=57)** → 取得并展示二维码 → 顾客扫码完成真实付款 → **[回调接口](https://open.shouqianba.com/docs/payment/70?category_id=54)**或**[查询接口](https://open.shouqianba.com/docs/payment/71?category_id=54)**确认真实交易 → 成功后幂等履约 → 售后需要时调用**[退款接口](https://open.shouqianba.com/docs/payment/72?category_id=54)**。

## 准备二维码业务信息

- 目标：为本次二维码生成请求建立可追踪的业务记录。
- 输入来源：门店、设备、展示内容和业务上下文来自商户系统。
- 商户系统处理：生成全局唯一的二维码生成请求流水号，并保存请求状态。
- 输出用途：定位本次二维码生成请求，不作为真实支付成功凭证。
- 下一步：调用二维码生成接口。

## 生成聚合二维码

- 目标：取得可展示给顾客扫描的二维码内容或图片地址。
- 调用接口：**[二维码生成接口](https://open.shouqianba.com/docs/payment/100?category_id=57)**。
- 输入来源：二维码生成流水号和业务内容来自上一步；终端参数来自当前设备的安全配置。
- 签名凭证：使用当前终端的`terminal_sn`和`terminal_key`。
- 输出用途：读取并保存响应中的二维码内容或二维码图片地址。
- 下一步：生成成功则展示二维码；响应缺少可展示内容时按失败处理并重新请求。

二维码生成成功不创建真实支付订单，不代表支付成功，不能触发履约。

## 展示二维码

- 目标：让顾客在有效期内扫描正确的二维码。
- 输入来源：只使用服务端返回并校验过的二维码内容或图片地址。
- 页面处理：明确显示应付业务信息和二维码有效状态；过期后立即停止展示。
- 输出用途：顾客扫码后进入收钱吧承接的实际支付页面。
- 下一步：页面进入“等待付款”，商户后台等待真实交易回调或查询真实交易。

## 关联真实交易

顾客扫码付款后，会产生真实交易。商户系统需要分别保存：

| 标识                 | 来源                           | 用途                       |
| -------------------- | ------------------------------ | -------------------------- |
| 二维码生成请求流水号 | 商户在调用二维码生成接口前生成 | 排查二维码是否成功生成     |
| 真实交易商户订单号   | 扫码后实际支付链路产生         | 查询、回调、退款和幂等履约 |
| 收钱吧订单号         | 真实交易结果返回               | 与收钱吧核对实际交易       |

不要把二维码生成请求流水号直接当作已支付订单。实际字段名称和返回位置以二维码及真实支付接口文档为准。

## 接收真实交易回调

- 目标：取得顾客扫码后真实交易的异步结果。
- 对接接口：**[回调接口](https://open.shouqianba.com/docs/payment/70?category_id=54)**。
- 输入来源：收钱吧向商户公网回调地址发送的真实交易通知。
- 商户系统处理：验签，通过真实交易商户订单号定位订单，幂等更新状态。
- 输出用途：确认顾客是否真正付款。
- 下一步：最终成功后履约；非最终状态保持等待并主动查询。

## 查询真实交易

- 目标：在回调延迟、页面中断或结果未知时确认真实交易状态。
- 调用接口：**[查询接口](https://open.shouqianba.com/docs/payment/71?category_id=54)**。
- 输入来源：使用顾客扫码后真实交易的商户订单号或收钱吧订单号，不使用二维码生成请求流水号。
- 输出用途：与回调共用一个真实交易状态机。
- 下一步：最终成功则履约；最终失败则结束；仍未知则按业务规则等待或人工核实。

## 确认成功并履约

- 触发条件：服务端从真实交易回调或查询取得最终支付成功。
- 执行动作：出货、开闸、打印、发券或更新业务状态。
- 幂等要求：以真实交易商户订单号作为幂等键，只履约一次。

二维码生成成功、顾客已扫码或支付页面显示成功，都不能直接触发履约。

## 发起退款

- 目标：退回已经确认成功的真实交易款项。
- 调用接口：**[退款接口](https://open.shouqianba.com/docs/payment/72?category_id=54)**。
- 输入来源：使用真实支付订单标识和唯一退款流水号。
- 输出用途：保存并跟踪真实退款流水。
- 下一步：退款结果非最终或请求超时时，查询原退款流水。

二维码生成请求本身没有可退款资金，不能对二维码生成流水发起退款。

## 完成标准

- [ ] 二维码生成流水和真实交易订单分开保存。
- [ ] 生成成功只展示二维码，不触发履约。
- [ ] 页面在二维码过期后停止展示。
- [ ] 回调和查询使用真实交易订单标识。
- [ ] 只有真实交易最终成功才履约。
- [ ] 重复扫码、重复回调和重复查询不会重复履约。
- [ ] 退款只针对真实支付订单。