NewAPI 商户如何通过 ePay 协议对接快米兔聚合支付：充值、回调与对账全流程

自建 AI 中转站或使用 NewAPI、OneAPI 等开源面板的团队，在完成模型路由和密钥管理后，往往会进入商业化收款阶段。支付通道的稳定性直接影响用户体验和资金安全。常见的 ePay 易支付协议在国内部署友好、接口标准，而快米兔聚合支付兼容常见 ePay 协议，已经接入 ePay 的充值页通常只需更换网关地址和商户密钥即可完成切换，下单与回调逻辑一般不用重写。本文以 NewAPI 场景为例，梳理从配置到上线的完整支付对接流程。

先理解整体架构。NewAPI、OneAPI 等面板通常以 OpenAI 兼容协议为核心，对下游用户暴露 /v1/chat/completions 等接口，上游可以接入官方接口或任意 OpenAI 兼容上游。用户先通过人民币充值获得额度，再按 token 消耗扣减。支付系统需要完成三件事：接收用户付款、验证异步回调、为对应账户增加余额。这个链路里，面板负责额度与调用，快米兔聚合支付负责收款和结算，两边通过 ePay 协议交互。

快米兔聚合支付的接入从商户后台开始。登录商户后台，获取商户 ID 和商户密钥，这两个值是后续接口调用的身份凭证，建议通过环境变量注入，不要硬编码进代码仓库。支付网关地址由快米兔聚合支付提供，通常是 ePay 协议兼容的提交地址。与此同时，需要配置异步通知地址和同步跳转地址：前者用于支付完成后服务器主动回调，后者用于用户浏览器跳回页面。两个地址都必须是公网可访问的 HTTPS 地址，本地调试需使用内网穿透临时暴露。

在 NewAPI 或 OneAPI 后台的支付设置中，选择 ePay 类型，将默认接口地址替换为快米兔聚合支付的网关地址，并填入商户 ID 和商户密钥。由于快米兔聚合支付兼容常见 ePay 协议，已经接入 ePay 的充值页不需要重写支付发起和回调主体，一般只需替换网关和凭据。如果面板未内置 ePay 适配器，则需要手动实现支付发起与回调处理两段逻辑，协议本身仍按 ePay 规范处理。

支付发起的关键是构造签名。ePay 协议通常使用 MD5 签名，将 money、name、notify_url、out_trade_no、pid、return_url、sitename、type 等参数按键名升序排列，拼接成 key=value&key=value 字符串，末尾追加商户密钥，再进行 MD5 得到 sign。签名错误是常见问题，原因多集中在参数未按 ASCII 码排序、金额字段误传浮点数、密钥前后存在多余空格。建议开发阶段先使用签名校验工具逐项核对，确保发送给快米兔聚合支付网关的请求参数正确。

异步回调验证是资金安全的核心。用户在支付完成后，快米兔聚合支付会按照配置的 notify_url 发送 POST 请求，携带订单号、金额、支付状态和 sign。服务端收到回调后，必须用相同算法重新计算 sign，与请求中的 sign 比较，一致才认定合法。验证通过后，查询本地订单状态，只有处于待支付状态的订单才执行充值入账，避免重复处理。处理完成后返回 success，否则网关会按策略重试。这个幂等处理加返回 success 的流程，在快米兔聚合支付的回调处理中同样适用。

订单号与对账也不可忽略。out_trade_no 是商户侧唯一订单号，建议用时间戳加随机字符串组合，避免并发重复。数据库中应建立订单表，记录订单号、用户 ID、金额、状态、创建时间和回调时间。快米兔聚合支付按成交金额计费，交易费率为 1%，无开户费、无年费等其他费用。资金为直清模式，进入商户结算账户，T+1 结算。日常对账时，以本地订单状态和快米兔聚合支付后台的结算记录为准，重点核对回调和入账金额是否一致。

计费精度属于 NewAPI 面板自身需要维护的部分。用户充值后获得的是面板内的 token 额度或积分，每次调用需要根据不同模型的 input token 和 output token 消耗实时扣减。不同上游模型单价差距较大，面板需要维护模型价格表。这部分逻辑与支付相对独立，快米兔聚合支付只处理用户的人民币充值订单，不参与 token 定价或额度计算，避免把支付入账和模型计费混在一起。

上线前建议完成几项检查。第一，在测试环境跑通一次完整流程，包括支付发起、异步回调、余额变更；第二，确认回调地址在服务重启后仍可访问，避免进程管理导致回调丢失；第三，核对后台配置的异步通知地址与代码处理路由完全一致，包括末尾斜杠；第四，检查服务器时区，订单超时判断依赖时间戳，时区不一致会造成状态异常。这些细节在开发阶段容易被忽略，却是生产环境常见故障来源。

整体来看，在 NewAPI、OneAPI 等面板已经接入 ePay 的情况下，切换到快米兔聚合支付的成本很低，重点是替换网关地址和商户密钥后重新验证签名与回调。把签名校验、幂等处理、订单记录和上线检查做扎实，就能让用户充值、异步回调、入账与 T+1 对账形成稳定闭环。