樱花支付运维管控
详情介绍
樱花支付插件（YHpay）使用说明
版本：1.0.1 ｜ 作者：kuakeba.cn ｜ 适用宿主：BBS社区版
对接樱花码支付（yhkk.cn）的金币充值通道：支付宝 / 微信支付 / QQ钱包 / 支付宝当面付统一下单，MD5 验签异步回调，支付成功自动发放金币到账。深度集成 ZsAdmin 社区货币体系，与「支付中心」「VIP 会员」共用同一套余额与流水。
一、功能概览
- 四种支付方式：支付宝
alipay、微信支付wxpay、QQ钱包qqpay、支付宝当面付dmf，后台可勾选前台展示渠道 - 统一下单跳转：易支付风格协议，
{gateway}/submit.php携带签名参数跳转樱花收银台 - MD5 验签回调：异步
notify+ 同步return双通道，验签 + 交易状态 + 商户号 + 金额一致性四重校验，防伪造防篡改 - 沙箱模式：不跳转真实通道，前台「模拟支付」即可完成订单联调
- 货币体系融合：
- 履约走社区共享账本 Coin::creditActor，金币余额 / 流水与社区打赏、提现、兑换完全互通
- 已安装「支付中心」时自动沿用其金币名称、金币汇率与充值套餐；未安装时使用本插件配置兜底
- 支持会员与管理员双主体充值（管理员到账到 admin 账户）
- 充值套餐：预设套餐 + 自定义金额，套餐金币可覆盖全局汇率
- 后台订单管理：订单列表（搜索 / 状态 / 方式筛选）、手动补单、删除订单
- 安全细节：
- 回调金额必须与订单金额一致，防止「下大单付小单」
- 订单 1 小时过期自动关闭
- 履约幂等 + 事务保护，重复回调不重复到账
- 结果页自动轮询：待支付订单 3 秒轮询状态，到账自动刷新
二、运行环境
- PHP 8.0+（本机 8.0.2 实测可用）
- 已安装并启用「社区」（community）宿主插件（金币账本依赖）
- 樱花码支付商户账号：https://yhkk.cn/ 注册开通
三、安装
- 把
plugins/YHpay目录整体上传到项目plugins/下。 - 后台「应用中心 → 樱花支付 → 安装」（或「更新」升级）。
- 安装时自动执行
install.sql创建订单表yhpay_order，并注册后台菜单「樱花支付」。
旧版本升级会自动补列 actortype / adminid，无需手动改表。
卸载会删除订单表并注销菜单，卸载前请先备份。
四、配置项
后台「应用中心 → 樱花支付 → 配置」：
| 配置项 | 说明 |
|---|---|
启用樱花支付 enable | 关闭后前台充值入口与回调均不可用 |
沙箱模式 sandbox | 开启后不跳转真实通道，可用「模拟支付」完成订单测试（联调推荐） |
樱花商户ID pid | 登录 yhkk.cn 注册后，在「商户信息」中获取 |
樱花商户密钥 key | 用于 MD5 签名，请妥善保管，勿泄露 |
樱花接口地址 gateway | 不要末尾斜杠，默认 https://yhyhpay.cn |
支付方式 types | 决定前台展示的支付渠道，可多选（支付宝 / 微信 / QQ钱包 / 当面付） |
网站名称 sitename | 展示在樱花支付收银台的网站名，可留空 |
金币汇率（兜底）coin_rate | 1 元兑换多少金币（可含小数）。已安装「支付中心」时自动沿用其汇率，此项不生效 |
充值套餐（兜底）recharge_plans | 每行一条「金额:金币」，如 6:60。已安装「支付中心」时自动沿用其套餐 |
五、樱花商户后台配置
登录樱花码支付商户后台，在「商户信息」中确认以下回调地址（一般下单时由接口参数自动携带，无需手动填写）：
| 类型 | 地址 |
|---|---|
| 异步通知 notify_url | https://你的域名/yhpay/notify |
| 同步跳转 return_url | https://你的域名/yhpay/return |
两个地址在下单参数中自动携带本站域名，换域名后无需改配置。
六、前台入口
| 页面 | 地址 | 说明 |
|---|---|---|
| 充值页 | /yhpay/recharge | 会员中心侧边栏「樱花充值」入口进入 |
| 充值结果页 | /yhpay/recharge/result?order_no=xxx | 支付完成自动跳回，待支付时 3 秒轮询自动刷新 |
| 状态接口 | /yhpay/status?order_no=xxx | JSON 返回订单状态，供轮询使用 |
充值流程：选择套餐（或自定义金额）→ 选择支付方式 → 跳转樱花收银台扫码支付 → 樱花异步通知到账 → 同步跳回结果页展示。
七、沙箱联调
- 后台配置开启「沙箱模式」。
- 前台充值页正常选择套餐与支付方式，点击「立即充值」。
- 系统自动执行模拟支付并跳转到结果页，金币即时到账。
- 联调完成后关闭沙箱，填入真实
pid/key即可上线。
沙箱模式下回调接口不验签，生产环境务必关闭沙箱。
八、后台订单管理
「樱花支付」菜单进入订单列表：
- 搜索：订单号 / 用户名 / 樱花单号模糊匹配
- 筛选：状态（待支付 / 已支付 / 已关闭）、支付方式
- 手动补单：回调丢失时对订单补发金币（幂等，已履约订单不会重复到账）
- 删除订单：仅删除订单记录，已发放金币不受影响
列表查询时自动关闭超过 1 小时未支付的订单。
九、数据表说明
{前缀}yhpay_order 订单表关键字段：
| 字段 | 说明 |
|---|---|
order_no | 商户订单号（YH + 时间戳 + 随机数），唯一索引 |
actor_type | 下单主体 user / admin |
userid / adminid | 会员ID / 管理员ID |
type | 支付方式 alipay / wxpay / qqpay / dmf |
amount / gold | 支付金额（元）/ 到账金币 |
status | 0 待支付 / 1 已支付 / 2 已关闭 |
fulfilled | 0 未履约 / 1 已履约（金币已发放） |
trade_no | 樱花支付订单号 |
金币流水写入社区 communitycoinlog（类型 recharge 在线充值），reftype=yhpayorder 可回溯源单。
十、与其他插件的关系
| 插件 | 关系 |
|---|---|
| 社区 community | 必需。金币账本 Coin、会员体系、前台布局均依赖 |
| 支付中心 payment | 可选。已安装时自动沿用其金币名称 / 汇率 / 充值套餐，两个通道余额互通 |
| VIP 会员 vip | 可选。VIP 现金套餐走支付中心下单，本插件负责的金币可用于 VIP 金币套餐 |
十一、常见问题
Q：支付成功但金币未到账？
A：先到后台「樱花支付」订单列表确认订单状态。已支付未履约时点「补单」即可；待支付说明异步回调未到达，检查站点能否被外网访问（回调地址必须是公网可达域名），或手动补单。
Q：回调返回 fail？
A：依次排查：① 商户密钥 key 是否填错；② 回调金额与订单金额是否一致；③ 是否误开沙箱后又用真实通道下单（沙箱/生产校验逻辑不同）。
Q：管理员充值金币到哪？
A：到账到管理员账户（admin 表 gold 字段），与会员账户体系隔离，社区账本中主体类型为 admin。
Q：充值套餐不生效？
A：已安装「支付中心」时本插件套餐与汇率不生效，自动沿用支付中心配置；请前往「应用中心 → 支付中心 → 配置」修改。
Q：可以只用 QQ 钱包吗？
A：可以，在配置「支付方式」中只勾选 QQ钱包即可，前台只展示已勾选渠道。
更新记录 （1）
-
v1.0.0
2026-10-16
首次发布
QQ官方交流群