支付、订单与退款

用途

管理员可从后台侧边栏进入「运营 → 支付管理」（/admin/billing），发布并启停 Stripe、PayPal 配置，查询订单及发起整单退款；积分余额与人工发放统一位于「用户与积分」的用户详情中。普通用户可从顶部账号菜单的「充值」进入「个人中心 → 积分充值」。页面集中展示可用、冻结、已消费和已冲正积分，并按区域排列支付渠道、积分套餐、使用记录和订单记录；账号菜单同时提供当前积分概览。支付完成返回充值页后，系统会根据订单号主动向支付渠道核验结果；即使本地 Webhook 延迟或未送达，也会在确认到账后补发积分并刷新订单。页面会提示支付成功、确认中、取消或确认失败，提示后会自动清理一次性回跳参数，刷新页面不会重复显示旧结果。充值套餐默认收起在「积分商店」中，点击「充值」后在弹窗内选择套餐；积分使用记录支持分页浏览。

使用前准备

配置版本

每次保存都会生成不可变配置版本。密钥加密保存且不会通过管理 API 回显；新订单使用当前版本，旧版本继续用于原订单的 Webhook 验证、查询和退款。测试环境与正式环境相互隔离。

Webhook 地址分别为：

/api/webhooks/payments/stripe/test 或 /live
/api/webhooks/payments/paypal/test 或 /live

操作步骤

配图占位：管理后台的支付 Provider、订单和积分标签页。

发布测试环境配置并在渠道后台登记对应 Webhook。
启用配置后创建测试订单，完成支付或 PayPal capture。
在订单列表核对到账状态；符合条件时发起整单退款。

本地自动配置

在本地开发时，后台勾选「自动配置 Webhook」并填写渠道私钥/密钥即可；系统会自动检查并通过 Homebrew 安装缺失的 Stripe CLI 或 cloudflared，启动转发或 PayPal 临时 HTTPS 隧道，注册并写入凭据。也可运行 npm run payment:webhook:local 完成同样操作。两种模式都会自动启用测试环境配置，按 Ctrl+C 可停止转发；非 macOS 环境需预先安装对应工具。

保存失败时，后台会通过统一错误提示显示接口错误和具体原因。

结果与状态

管理员先发布包含币种、最小货币单位金额和积分数量的固定套餐；初始套餐按 1 USD = 1000 积分 提供默认值，套餐名称、积分、金额、币种、排序和启停状态仍可在后台编辑。后台录入的 USD 100 表示 100 美分，列表会换算显示为 1.00 USD。客户端向 POST /api/payments/orders 只发送 Provider、环境、packageId 和幂等键，不能自行指定价格或积分。请求格式或字段非法时接口返回参数错误；未被业务处理的基础设施故障保留为服务端错误，客户端应使用原幂等键重试。平台订单先保存套餐价格快照，因此编辑套餐不会改变已有订单；超时或结果不明会进入对账，不会用新幂等键重复创建支付。

PayPal 获得用户授权后，客户端调用 POST /api/payments/orders/{orderId}/capture。积分只在签名有效的付款事件或渠道查询确认付款后到账。

权限和边界

整单退款仅允许订单积分批次仍满足 available=issued、reserved=0、consumed=0；如果该订单已经发放邀请奖励，双方奖励批次也必须完整未使用。提交退款后相关批次保持锁定；渠道超时或状态未知时只能由对账继续推进，渠道明确拒绝才解除锁定。退款成功会同步冲正未使用的双方邀请奖励。

拒付、争议和后台外部退款会使用原支付号关联订单，并立即冲正该批次尚可用的积分。已经冻结或消费的部分不会形成负余额，订单会标记为人工处理。争议关闭或商户胜诉事件不会误触发新的资金撤回。

事件与对账

支付事件使用 RECEIVED / PROCESSING / PROCESSED / FAILED 收件箱状态和处理租约。订单付款、积分批次、流水与事件完成在同一数据库事务提交。Watchdog 会推进卡住事件、未知订单、退款处理中订单、资金撤回及账户汇总校验。

常见问题

为什么退款一直显示处理中？

渠道结果未知时系统会保持批次锁定并等待对账，避免重复退款或积分继续消费。