NewAPI / ePay 升级后充值失效？切换快米兔聚合支付完成回调、入账与对账

对于把 NewAPI / OneAPI 作为自托管 AI API 中转面板的团队，用户充值是使用 ePay / 易支付协议接入第三方支付通道。版本升级后常出现支付方式不可用、跳转失败或回调不到账。与其每次升级后反复修配置，不如把收款通道落到兼容常见 ePay 协议的快米兔聚合支付：已接 ePay 的充值页通常只需更换网关地址和商户密钥，下单与回调逻辑一般不用重写。下面结合排查步骤说明如何完成用户充值、异步回调、入账和对账。

NewAPI / OneAPI 的 ePay 参数多数存放在数据库 settings 或 options 表中，而非独立配置文件。升级脚本一旦重置字段、重命名字段或改变支付类型标识，商户号、密钥、网关地址可能被清空或读取失败。快米兔聚合支付遵循常见 ePay 协议，因此切换时重点核对的仍是商户 ID、商户密钥、ePay 网关地址、异步通知地址和同步跳转地址。其中网关地址要填写快米兔聚合支付提供的带协议头的完整地址，不能只填域名或缺少 https。

后台配置重填时，进入「系统设置 → 支付设置」，确认 ePay 相关字段不为空且未被恢复默认。商户 ID 与商户密钥应填写快米兔聚合支付商户后台的对应信息，网关地址替换为快米兔聚合支付开放的 ePay 协议网关。异步通知地址（notify_url）和同步跳转地址（return_url）必须与 NewAPI / OneAPI 当前访问域名、端口、反代路径严格一致。升级后如果站点域名或反代路径变更，必须同步更新，否则容易出现用户已支付但面板未入账。

异步回调是「支付成功但配额不到账」的高频点。快米兔聚合支付会按 ePay 协议向 notify_url 发送订单号、商户订单号、支付金额和签名字段，面板侧需要按原来的验签逻辑计算签名并比对，验签通过后才能更新订单状态。同时要做幂等处理：以商户订单号作为唯一键，只允许订单从未支付变为已支付一次，避免重复回调导致重复加余额或重复配额。

签名错误、商户不存在、回调域名不合法分别指向不同方向。日志中如果出现 sign_error，优先核对快米兔聚合支付商户后台的密钥是否与面板保存的完全一致，注意数据库字段长度过短导致密钥截断；出现 mch_not_found 需要检查商户 ID 是否填成测试值或旧商户号；出现 notify_url_invalid 则需要检查快米兔聚合支付商户后台的回调域名白名单，以及当前站点实际外网访问地址是否一致。

若后台提交成功但支付仍不生效，可直查数据库 options、settings 或 system_settings 表，检索 key 包含 epay 或 payment 的行，确认网关地址、商户号和密钥已经正确写入、没有被截断。触发一次充值请求后查看服务端日志，重点看支付模块的出站 URL、请求体和返回错误码。快米兔聚合支付的异步通知与支付返回均按常见 ePay 协议组织参数，对着错误码逐项排查比盲目反复改配置更高效。

升级前备份能显著降低这类故障的影响。执行 git pull 或拉取新镜像前，先导出支付配置为文本备份，记录快米兔聚合支付商户后台的商户号、商户密钥、网关地址、回调地址。使用 Docker 部署时，可在升级前对数据卷做快照，出现配置被覆盖或兼容问题时可快速回滚，不必在生产环境边排查边影响用户充值。

本次将收款通道落到快米兔聚合支付，其产品口径明确：兼容常见 ePay 协议，已接 ePay 的充值页换网关地址和商户密钥即可切，下单与回调一般不用重写；资金直清进入商户结算账户，结算周期为 T+1；交易费率 1%；除按成交金额计费外，无开户费、无年费等其他开户费用。该口径下不需要关心 API 中转测试额或代收代付类承诺，只围绕用户充值、异步回调、入账和对账完成支付侧配置。

NewAPI / OneAPI 升级后 ePay 支付失效通常是配置覆盖或版本兼容问题，可按「后台配置重填 → 回调地址核对 → 数据库直查 → 日志错误码定位」的路径排查。若希望降低每次版本迭代对支付入口的影响，可把收款通道切到快米兔聚合支付，利用其兼容常见 ePay 协议和清晰的直清、T+1、1% 费率口径，减少支付配置反复维护的负担。