# 公众号与内部H5支付接口接入步骤
[返回产品介绍](产品介绍.md) · [查看注意事项](注意事项.md)
## 开始前
开始本场景前，应已完成[开发前准备](../开始接入/开发前准备.md)，并准备：
- 当前门店和设备对应的终端参数。
- 可通过HTTPS访问的商户下单页面、结果页和服务端回调地址。
- 能从可信代理链取得顾客手机真实公网IP的服务端能力。
- 能在页面关闭或网络中断后继续查询订单的后台任务。
## 接口调用时序图
创建商户订单 → 服务端生成**[跳转支付接口](https://doc.shouqianba.com/zh-cn/api/wap2.html)**地址 → 页面302跳转收钱吧收银台 → 顾客完成付款 → **[回调接口](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://doc.shouqianba.com/zh-cn/api/wap2.html)**。
- 输入来源：商户订单号、金额和商品简介来自已保存订单；`return_url`、`notify_url`来自服务端配置；顾客IP来自当前手机请求的可信代理链；终端参数来自安全配置。
- 签名方式：按跳转支付接口文档生成签名和完整URL，不在浏览器端计算签名。
- 输出用途：得到本次订单的跳转支付URL。
- 下一步：将URL返回给商户页面，由页面执行302跳转。
`return_url`用于顾客完成或退出支付后的页面导航；`notify_url`用于收钱吧向商户后台发送异步交易结果。两者用途不同。
## 跳转收钱吧收银台
- 目标：让顾客从商户H5页面进入收钱吧收银台并完成支付验证。
- 输入来源：只使用商户后台生成的完整跳转URL。
- 页面处理：通过302重定向打开URL，不修改参数、顺序或签名内容。
- 输出用途：收钱吧根据顾客所在应用选择支付渠道并展示支付控件。
- 下一步：页面显示“支付处理中”，同时由商户后台启动结果确认。
如果生成的URL直接跳回`return_url`并携带失败信息，应先检查URL参数和签名，不能将其当作支付失败后重新扣款。
## 处理页面返回
- 目标：在顾客返回商户页面后给出正确提示。
- 输入来源：浏览器跳转到`return_url`时携带的页面信息。
- 页面处理：只展示“正在确认支付结果”，并向商户后台查询本地订单状态。
- 输出用途：改善顾客体验，不作为支付成功凭证。
- 下一步：由商户后台等待回调或主动查询。
顾客可能关闭浏览器、停留在支付页或伪造前端参数，因此页面返回不能直接触发出货、开闸或发券。
## 接收支付回调
- 目标：异步取得订单最终结果。
- 对接接口：**[回调接口](https://open.shouqianba.com/docs/payment/70?category_id=54)**。
- 输入来源：收钱吧向`notify_url`发送的原始通知。
- 商户系统处理：验签，通过商户订单号定位原订单，并与查询共用状态机完成幂等更新。
- 输出用途：确认交易最终结果。
- 下一步：成功落库后返回`success`；最终成功时只履约一次。
## 主动查询补偿
- 目标：补偿页面关闭、回调延迟、跳转中断或支付结果未知。
- 调用接口：**[查询接口](https://open.shouqianba.com/docs/payment/71?category_id=54)**。
- 输入来源：使用创建订单时保存的原商户订单号或收钱吧订单号。
- 输出用途：更新同一订单状态，不创建新的扣款。
- 下一步：最终成功则履约；最终失败则结束；达到查询上限仍未知则转人工核实。
## 完成履约
- 触发条件：服务端回调或查询已经确认最终支付成功。
- 执行动作：出货、开通服务、发券或更新业务权益。
- 幂等要求：以商户订单号做唯一约束，页面返回、回调和查询并发时也只履约一次。
## 发起退款
- 目标：退回已经确认支付成功的订单资金。
- 调用接口：**[退款接口](https://open.shouqianba.com/docs/payment/72?category_id=54)**。
- 输入来源：原支付订单标识、退款金额、退款原因和唯一退款流水号来自商户售后系统。
- 输出用途：保存退款流水，并关联原支付订单。
- 下一步：非最终结果或请求超时时查询原退款流水。
## 完成标准
- [ ] 跳转URL只在服务端生成。
- [ ] 页面使用302打开完整URL，不修改签名参数。
- [ ] `return_url`只用于导航，`notify_url`只用于异步通知。
- [ ] 顾客手机真实公网IP能够被正确取得并上送。
- [ ] 页面返回不会直接更新订单为成功。
- [ ] 回调和查询更新同一订单并幂等履约。
- [ ] 跳转中断和浏览器关闭后仍可确认结果。
- [ ] 结果未知时不会生成新订单重复扣款。
收钱吧开放平台