## 开始前

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

- 已经与支付商户关系配置完成的目标小程序`appid`。
- 当前登录顾客在该小程序`appid`下的`openid`。
- 当前门店和设备对应的终端参数。
- 可公网访问的`notify_url`和可执行主动查询的后台任务。

## 接口调用时序图

![小程序支付顾客支付接口调用时序图](https://img-hub.wosaimg.com/file/2026/08/06/529982edbce57eff.png)

创建商户订单 → 服务端调用**[预下单接口](https://doc.shouqianba.com/zh-cn/api/interface/precreate.html)** → 将`wap_pay_request`交给小程序 → 小程序调用`wx.requestPayment` → **[回调接口](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)**。

## 配置小程序关系

- 目标：让收钱吧能够为目标小程序创建微信支付订单。
- 配置来源：商户主体、小程序`appid`和支付开通信息由商户及收钱吧对接人员确认。
- 完成结果：正式商户与目标小程序关系已配置，当前支付终端可用于该小程序。
- 下一步：在小程序登录链路中取得当前顾客`openid`。

如果商户主体与小程序主体不同，可能需要按对接要求完成联合运营等额外配置。关系未完成前，不要进入支付测试。

## 创建商户订单

- 目标：在唤起微信支付前保存一笔待支付订单。
- 输入来源：商品、金额、顾客、门店和业务信息来自商户系统。
- 商户系统处理：生成全局唯一的商户订单号，保存订单金额、当前小程序`appid`和`openid`所属关系。
- 输出用途：用于预下单、查询、回调、退款和幂等履约。
- 下一步：调用预下单接口。

## 调用预下单

- 目标：创建收钱吧支付订单，并取得微信小程序调起参数。
- 调用接口：**[预下单接口](https://doc.shouqianba.com/zh-cn/api/interface/precreate.html)**。
- 输入来源：商户订单号、金额和商品简介来自已保存订单；`payer_uid`取当前顾客在目标小程序下的`openid`；`extended.sub_appid`取已配置的小程序`appid`；支付方式按小程序支付配置；`notify_url`来自服务端配置。
- 签名凭证：使用当前终端的`terminal_sn`和`terminal_key`。
- 输出用途：保存收钱吧订单号和交易状态，把`wap_pay_request`返回给发起订单的小程序页面。
- 下一步：响应允许继续支付且`wap_pay_request`完整时，调起微信支付；否则按响应结果结束或查询原订单。

完整字段、取值、类型和必填规则以预下单接口文档为准。

## 调起微信支付

- 目标：让顾客在微信原生收银台确认付款。
- 调用能力：小程序端`wx.requestPayment`。
- 输入来源：将预下单响应中的`wap_pay_request`按微信要求映射给`wx.requestPayment`，不要由小程序自行生成或改写签名参数。
- 输出用途：小程序端只用于展示支付完成、取消或失败提示。
- 下一步：无论前端返回成功、失败、取消或页面被关闭，商户后台都按原订单接收回调或主动查询。

`wx.requestPayment`返回成功不等于商户已经取得最终支付结果，不能直接触发履约。

## 接收支付回调

- 目标：异步取得订单最终状态。
- 对接接口：**[回调接口](https://open.shouqianba.com/docs/payment/70?category_id=54)**。
- 输入来源：收钱吧向预下单时提供的`notify_url`发送原始通知。
- 商户系统处理：验签，通过商户订单号定位原订单，并与查询共用状态机幂等更新。
- 输出用途：确认最终交易结果。
- 下一步：成功落库后返回`success`；最终成功时只履约一次。

## 主动查询

- 目标：在预下单后主动确认结果，补偿前端和回调的不确定性。
- 调用接口：**[查询接口](https://open.shouqianba.com/docs/payment/71?category_id=54)**。
- 输入来源：使用预下单保存的原商户订单号或收钱吧订单号。
- 输出用途：与回调更新同一订单。
- 下一步：最终成功则履约；最终失败则结束；仍非最终状态则按本场景节奏继续查询。

预下单成功5秒后开始查询；第0至1分钟每3秒一次，第1至5分钟每10秒一次，第6分钟执行最后一次查询。

## 完成履约

- 触发条件：商户后台通过验签回调或查询确认最终支付成功。
- 执行动作：开通服务、出货、发券或更新权益。
- 幂等要求：以前述商户订单号为幂等键，只创建一个履约任务。

## 发起退款

- 目标：退回已经确认支付成功的订单资金。
- 调用接口：**[退款接口](https://open.shouqianba.com/docs/payment/72?category_id=54)**。
- 输入来源：原支付订单标识、唯一退款流水号、金额和原因来自商户售后系统。
- 输出用途：保存退款流水并关联原支付订单。
- 下一步：退款非最终或请求超时时查询原退款流水。

退款只能由商户后台发起，小程序端不得持有退款签名凭证。

## 完成标准

- [ ] 正式商户与目标小程序关系已经配置。
- [ ] `openid`属于当前`extended.sub_appid`对应的小程序。
- [ ] 预下单结果和`wap_pay_request`已正确保存和转交。
- [ ] `wx.requestPayment`返回不会直接触发履约。
- [ ] 回调和主动查询更新同一订单。
- [ ] 轮询节奏、4分钟支付有效期和第6分钟最终查询已经实现。
- [ ] 结果未知时不会履约或重复发起支付。
- [ ] 退款只由服务端发起。