对接排错：10 个常见错误及解决方法
密钥错误、Webhook 一直收不到、签名始终不匹配：我们最常见的十个对接问题，每个都附有错误代码和解决方法。
发布于 10 十月 2026 阅读约 3 分钟
大多数对接问题并不是程序缺陷，而是小的设置错误，只要知道去哪里看就很容易修复。请先查看后台的 API 日志：您的服务器发送的每个请求都记录在那里，包括 PAYWISE 的响应和 error.code。
1. 密钥缺失或被截断
错误： INVALID_API_KEY。请严格按 Authorization: Bearer <key> 格式发送请求头，并完整复制密钥。注意复制粘贴时多出的空格或换行。
2. 正式环境用了沙盒密钥，或反之
pw_test_… 密钥只能看到沙盒付款，pw_live_… 密钥只能看到正式付款。用错密钥查询付款会得到 NOT_FOUND。请把密钥放在环境配置中，并确认服务器加载的是哪一个。
3. 服务器 IP 不在允许列表中
错误： IP_NOT_ALLOWED。该密钥设置了允许的 IP 列表，而请求来自其他地址。错误信息会显示 PAYWISE 看到的 IP：请在 API 密钥页面添加它。位于负载均衡器后面的服务器或新主机经常会更换出口 IP。
4. 返回 URL 不属于您的网站
错误： RETURN_URL_NOT_ALLOWED。return_url 必须使用 https://，且域名必须是您的有效网站之一（或其子域名）。请在网站与 Webhook 中添加该域名。
5. 用新金额重复使用订单号
错误： DUPLICATE_REFERENCE。相同内容的重复请求是安全的，会返回原来的付款。新的金额需要新的 merchant_reference。请阅读幂等性的工作原理。
6. Webhook URL 无法访问
Webhook 必须发送到公开的 https:// 地址。localhost 和内网 IP 地址都会被拒绝。使用发送测试 Webhook，并在投递历史中查看响应。如果防火墙只接受已知地址，请放行 Webhook 页面上列出的发送方 IP。
7. 签名始终不匹配
请用 Webhook 密钥对原始请求体（按收到时的原样）计算 HMAC-SHA256。先解析 JSON 再重新编码会改变字节内容，导致签名失败。还要确认使用的是当前密钥："创建新密钥"之后，旧密钥立即失效。可在文档中的签名工具里测试，并阅读验证 Webhook 签名。
8. 服务器响应慢或返回错误
请尽快以 HTTP 2xx 响应 Webhook，然后再处理耗时的工作（发邮件、更新库存）。其他响应都会被重试，看起来就像重复事件。请根据付款参考号，每个事件只处理一次。
9. 相信返回页面而不是 Webhook
顾客回到您的网站并不代表已经付款。只有在收到有效的 payment.paid Webhook，或通过 API 查询确认后，才把订单标记为已支付。
10. 请求过多
错误： RATE_LIMITED（同一个密钥每分钟超过 60 个请求）。不要密集轮询付款状态：等待 Webhook，并以逐渐增加的间隔重试。
仍然无法解决？
请在支持菜单中新建工单，附上请求时间、error.code 和您的网站，或通过 Telegram @paywise_asia 联系我们。请参阅如何快速获得帮助。
