故障排除

未收到付款

症状

• 客户说已经付款，但交易显示"Pending"或没有出现交易记录。

诊断步骤

1. 检查区块链：使用区块链浏览器（如 Etherscan、Blockchain.com）验证交易哈希。确认付款是否已发送到正确的地址。

1. 检查确认数：付款可能正在等待所需的确认次数。进入仪表盘 → Transactions，查看交易状态。

1. 检查金额：如果客户发送的金额少于要求的金额，除非启用了"Accept Underpayments"，否则交易将被标记为金额不足。

1. 验证地址：确保客户发送到了正确的钱包地址和正确的网络。一个常见错误是将 ERC-20 代币发送到 TRC-20 地址（不同网络，资金可能会丢失）。

1. 检查加密货币类型：验证客户是否使用了他们选择的加密货币进行支付，而不是同一网络上的其他代币。

解决方案

• 如果交易已在区块链上确认但未在 QuantaPay 中反映，请使用 check-transaction API 强制重新检查。
• 如果付款被发送到了错误的地址或错误的网络，QuantaPay 无法恢复这些资金。

Webhook 未触发

症状

• 付款在 QuantaPay 仪表盘中已完成，但您的服务器没有收到 Webhook 通知。

诊断步骤

1. 验证 Webhook URL：进入 Settings → Payments → Webhook，确认 URL 正确。

1. 检查端点可访问性：确保您的 Webhook 端点可通过 HTTPS 公开访问。使用 curl 测试：

   curl -X POST https://yoursite.com/wp-json/quantapay/webhook \
     -H "Content-Type: application/json" \
     -d '{"test": true}'

1. 检查服务器日志：查找发送到 Webhook 端点的 POST 请求。如果没有，问题出在传递环节。如果出现 500 错误，问题出在您的处理代码中。

1. 防火墙 / WAF：如果使用 Cloudflare，请确保 Webhook 端点已被允许（参见 WordPress / WooCommerce 了解 Cloudflare 配置）。

1. 检查 Webhook 状态：在仪表盘 → Transactions 中，"Webhook"列显示 1 表示该交易的 Webhook 已发送。

解决方案

• 修复 Webhook URL 或端点可访问性问题。
• 临时使用 Webhook 测试服务（webhook.site）来确认 QuantaPay 正在发送 Webhook。
• 作为备选方案，轮询 get-checkout-session API 来检查支付状态。

API 连接错误

症状

• API 调用返回错误、超时或意外响应。

常见问题

调试技巧

1. 使用 curl 测试：使用 curl 来确定问题是在您的代码中还是在 API 端：

   curl -X POST https://cloud.quantapay.app/api.php \
     -d "function=get-balances" \
     -d "api-key=YOUR_API_KEY"

1. 检查响应格式：所有响应遵循 {"success": true/false, ...} 格式。在访问 response 之前先解析 success 字段。

1. 记录请求日志：记录完整的请求和响应以便调试。

WordPress 插件问题

订单状态未更新

• 验证 Webhook URL 在 WordPress 和 QuantaPay Cloud 中都已配置。
• 检查 WordPress 调试日志（wp-content/debug.log）中的错误。
• 确保 WooCommerce 订单存在且处于"Pending"状态。

插件设置无法保存

• 清除所有缓存插件（WP Super Cache、W3 Total Cache 等）。
• 检查 wp-content/ 的文件权限。
• 验证数据库用户具有写入权限。

结账重定向不工作

• 确保网站的 SSL 证书有效。
• 检查浏览器控制台中的 JavaScript 错误。
• 验证 QuantaPay Cloud API 可从您的服务器访问。