NewAPI 对接 ePay 易支付场景下，快米兔聚合支付充值回调与对账实操全记录

自建 API 中转站时，NewAPI 仍是不少开发者用来做渠道聚合、Key 分组和按量计费的开源面板。它的上游可以接官方接口或任意 OpenAI 兼容上游，计费与充值则依赖独立的支付通道。常见的 ePay 协议已经在大量 NewAPI 站点中被采用，因此在支付侧把收款通道落到快米兔聚合支付，通常不需要推翻原有充值逻辑。

快米兔聚合支付兼容常见 ePay 协议。已经接入 ePay 的充值页，多数情况下只需把网关地址和商户密钥替换为快米兔聚合支付的对应参数，下单与回调一般不用重写。接入后资金为直清模式，进入商户结算账户，按 T+1 结算；交易费率为 1%，除按成交金额计费外，没有开户费、年费等其他开户费用。这个口径适合先把支付链路跑稳，再逐步扩展 NewAPI 的模型与用户规模。

联调前先准备好三组参数：快米兔聚合支付商户后台提供的商户号、商户密钥和网关地址，以及 NewAPI 后台支付设置里的异步通知地址 notify_url 和同步跳转地址 return_url。NewAPI 的支付渠道仍选择 ePay，但接口地址必须填快米兔聚合支付的网关地址，商户 pid 和 key 也替换为快米兔聚合支付的商户号与密钥。notify_url 需要公网可达，本地 Docker 部署 NewAPI 时可配合 ngrok 或 frp 暴露回调地址，否则支付成功后异步通知进不来。

签名环节最容易出问题。常见 ePay 协议使用 MD5 签名，参与签名的字段按参数名 ASCII 码升序排列，拼接成 key=value&key=value 形式，再在末尾追加 &key=商户密钥，对整串做 MD5。NewAPI 如果已经适配过 ePay，切换快米兔聚合支付后一般可沿用这套签名逻辑，但仍要逐字段核对，尤其是空值字段是否参与签名、金额是否按两位小数字符串处理。联调期间建议开启请求日志，完整记录发往快米兔聚合支付网关的请求报文和收到响应，便于签名不一致时定位。

测试订单可按真实充值链路走一遍：用户在 NewAPI 侧发起充值并填写金额，系统生成本地订单号后跳转到快米兔聚合支付收银台完成支付；支付成功后，网关向 notify_url 发送异步 POST，同时跳转 return_url。异步通知里通常包含 trade_no、out_trade_no、money、trade_status 等字段，交易成功时 trade_status 值为 TRADE_SUCCESS。NewAPI 收到通知后需要先验签，再核对订单号和实际金额，最后触发余额入账。notify_url 必须返回纯文本 success，否则网关会重试；同时要确认 NewAPI 对同一订单号做了幂等校验，避免重复入账。

对账时建议以快米兔聚合支付后台导出的交易明细为准，按 trade_no 和 out_trade_no 与 NewAPI 的充值记录逐笔核对。快米兔聚合支付为直清模式，资金进入商户结算账户并按 T+1 结算，交易费率固定为 1%，除按成交金额计费外无开户费、无年费。日常重点核对支付金额、到账金额、订单状态和入账时间，遇到支付成功但余额未变化，优先检查异步回调是否触达、签名是否通过、订单号金额是否匹配。

最后，回调收不到、余额不更新、重复通知这三类问题基本可以按固定路径排查：先确认 NewAPI 填写的网关地址和商户密钥是快米兔聚合支付的正式或沙箱参数；再确认 notify_url 能从公网访问；接着查看网关返回的签名错误码；最后检查入账逻辑的幂等和金额格式化。把这些问题在联调阶段暴露出来，上线后用户充值、配额发放和对账会更稳定。