NewAPI 对接 epay，教程看再多，真到上手还是会被一堆小问题卡住。这篇不写配置流程了，直接把站长群里被问得最多的 10 个问题集中答一遍，每个都给你能直接照着做的结论。如果你还没配过，建议先看这篇API中转站能否对接epay？2026适配说明，把参数和回调地址先弄明白，再回来对号入座。

问题一：填完参数下单就报「签名错误」，到底是哪里的问题？

签名错误是最高频的坑，但原因九成不在算法，在参数本身。按这个顺序排查：

  • KEY 有没有带空格或换行：从网页复制 32 位密钥，首尾很容易夹带不可见字符，一个空格就导致 MD5 全错。这个坑我专门写过一篇易支付支付失败排查里那个藏在密钥里的换行符，里面那个换行符最后花了半天才揪出来。
  • 网关地址末尾斜杠：文档写没写斜杠，你就照着抄，多一个少一个都可能 404 或签名对不上。
  • 服务器时间不准：epay 会校验时间戳，差几分钟直接拒，报错还看不出来。

如果这三样都没问题，就用一段标准代码单独算一次 sign，跟服务商文档示例对一遍。签名算法本身没什么玄学，参数排序、空值剔除、MD5 小写这三条规则，详细拆解看MD5签名完整解析：参数组装、排序、空值处理。

问题二：能跳收银台，但付完钱配额一直不加，怎么回事？

能跳收银台说明下单和签名都通了，问题出在「支付完成 → 回调 → 加配额」这段。配额不加，99% 是回调没进到 NewAPI 里。先做一件事：在服务器上 curl 一下回调地址，看返回是不是 200。

curl -I https://你的域名/api/pay/notify

如果 404 或 502，说明 Nginx 没把 /api/ 这个路径转发到 NewAPI 的端口上。这是最容易被忽略的一环——后台填了参数，前端也能下单，但回调地址在公网上根本访问不到，epay 发了通知也进不来。回调地址不生效的完整排查思路，可以参考易支付回调地址设置后不生效的常见案例。

问题三：回调地址到底填什么？要自己配 Nginx 吗？

NewAPI 保存配置后会自己生成回调地址，格式固定是 https://你的域名/api/pay/notify，你不用去改它，也不用在 epay 后台单独填。但你要保证这个地址公网可达，这就涉及 Nginx 反向代理：NewAPI 默认跑在某个端口（比如 3000），你需要一条 Nginx 规则，把 /api/ 前缀的请求转发到那个端口。

很多人以为「填了参数就完事」，结果 Nginx 只转发了根路径，没转发 /api/，导致回调 404。这一步是「配置」和「能用」的分水岭。回调收不到的五步排查法，看支付回调收不到的五步排查思路。

问题四：NewAPI 支持哪些支付方式？支付宝和微信怎么勾？

NewAPI 的易支付配置区一般有「启用支付宝」「启用微信」两个开关，勾上哪个，前端充值页就显示哪个入口。这两个开关只是决定前端展示，真正的支付能力取决于你的 epay 服务商有没有开通对应通道。

一个常见的误区：服务商只开了支付宝通道，你却在 NewAPI 里把微信也勾上了，结果用户选微信付款，要么跳转失败，要么下单报错。勾之前先跟服务商确认通道开通情况，别想当然。页面里其它海外支付配置（Stripe、Creep 之类）全部留空，填了会出现多余入口。

问题五：沙箱和生产参数到底有什么区别？为什么一定要先用沙箱？

沙箱是 epay 服务商提供的测试环境，产生的订单不结算真钱，专门用来验证整条支付链路。生产参数才是真收钱。区别就一句话：沙箱测坏了不赔钱，生产测坏了要退钱。

上线前必须先用沙箱跑通「下单 → 跳收银台 → 模拟付款 → 回调 → 加配额」全流程，每一步都确认无误，再换生产参数。大多数人跳过沙箱直接上生产，结果一上线就是「钱收了、配额没到」，用户骂完还得挨个退。沙箱阶段多花十分钟，后面省一天。

问题六：回调会不会重复到账？NewAPI 自己做了幂等吗？

会重复通知，但 NewAPI 做了幂等，正常不会重复加配额。原因是 epay 网关在没收到 success 返回时会隔一段时间重试，所以同一个订单的回调可能来好几次。NewAPI 内部按订单号去重，同一订单只入账一次。

但有个前提：这个幂等是 NewAPI 内置的，前提是你用它的原生回调。如果你后面接了第三方插件、或者自己写回调转发，就得自己补幂等逻辑，按订单号判断「已处理过就直接返回 success，不再加配额」。自己写回调的完整做法，包括验签、金额比对、事务幂等，看自研网关对接 epay 的完整教程。

问题七：服务器时间不准，到底会有什么后果？

时间不准的后果很隐蔽，而且报错看不出来。epay 网关会校验请求时间戳，服务器时间和标准时间差超过几分钟，可能直接拒掉下单请求，或者回调验签时判断超时。表现就是：后台配置看着都对，但下单偶尔失败、回调偶尔丢，排查起来毫无头绪。

上线前跑一句 date 看看，或者用 ntp 同步一次系统时间。这个动作几秒钟，却能排除掉一类「玄学故障」。

问题八：金额和配额的比例怎么设才对？

NewAPI 里一般有个「充值档位」或「配额比例」配置，比如 1 元 = 多少 token。这里填错，用户付的钱和你发的配额对不上，后面全是工单。设置的关键是：比例要和你对外宣传的价格一致，别自己拍脑袋定一个数，上线前用沙箱充一笔最小的，核对到账配额是不是你设的那个数。

另外注意，epay 下单的 total_fee 是金额，NewAPI 拿到金额后再按比例换算成配额入账。金额和配额是两套数，别混了。金额字段的传参规范，可以对照易支付 API 接口对接的参数表里的参数表看。

问题九：换了新域名或者新服务器，要改哪些地方？

换域名或服务器，不是简单搬个文件就完事，下面这几处要挨个改：

  • NewAPI 的站点域名配置，回调地址会跟着变；
  • Nginx 反向代理规则，指向新的 NewAPI 端口和域名；
  • epay 后台如果登记过回调域名或白名单，也要同步更新；
  • HTTPS 证书重新申请，绑到新域名上。

证书这块特别容易漏，换完域名忘了换证书，用户一访问就报安全警告，支付直接中断。证书过期导致支付中断的教训，看网站 HTTPS 证书过期导致支付中断的教训。

问题十：能不能脱离 NewAPI，自己写回调？要注意什么？

能，而且有些场景必须自己写（比如你要做自定义计费、阶梯充值，NewAPI 的固定逻辑满足不了）。但自己写回调，三道安全闸一道都不能省：

  1. 验签：用回调参数重算 MD5，和 epay 传来的 sign 对比，对不上直接丢弃；
  2. 金额比对：用回调里的金额和本地订单金额比对，防止有人伪造低价支付回调；
  3. 幂等：按订单号去重，同一订单只入账一次。

这三件事里，验签保证数据没被篡改，金额比对保证业务没被钻空子，幂等保证不重复到账，缺一不可。签名算法本身可以参考MD5 和 RSA 签名选型的区别选型，再配合事务做原子入账。如果你还在用老协议，注意发卡网接入 epay 时 V1 与 V2 的协议差异里的协议差异，别踩版本坑。

一张速查表，收藏起来

把这 10 个问题的现象和排查方向浓缩成一张表，遇到问题直接对号入座：

  • 签名错误 → 查 KEY 空格、网关斜杠、服务器时间
  • 能下单不加配额 → curl 回调地址，查 Nginx 转发
  • 回调 404 → Nginx 没转发 /api/ 前缀
  • 某个支付方式点不了 → 服务商没开通对应通道
  • 回调重复到账 → 自己写回调时漏了幂等
  • 偶尔下单失败 → 查服务器时间同步
  • 配额和金额对不上 → 查充值档位比例设置
  • 换域名后支付中断 → 查证书 + 回调域名 + Nginx

这 10 个问题基本覆盖了 NewAPI 对接 epay 的日常踩坑面，遇到新问题，先往「签名」「回调」「时间」「证书」四个方向查，比瞎找快得多。