跳到主要内容

常见问题

集成与 API​

开始使用需要什么？​

您需要一个 API Key（从管理页面的 Store 获取）和一个 callback URL（公共 POST 端点）来接收 webhook。然后调用 POST https://api.payerscan.com/payment/crypto 创建发票，并将客户重定向到 url_payment。参见快速入门。

API 的 Base URL 是什么？​

官方 API Base URL 为 https://api.payerscan.com。所有 API 请求必须使用 HTTPS。

创建发票时可以不发送 callback_url 吗？​

可以。但您不会收到 completed/expired webhook。只能通过 GET https://api.payerscan.com/invoice/:trans_id（轮询）查看状态。

速率限制是什么？​

  • POST /payment/crypto： 5 次请求/秒，最多 60 次请求/分钟（按 API Key 计，回退到 IP）。
  • GET /invoice/:trans_id： 20 次请求/秒，最多 200 次请求/分钟。

超出限制 → HTTP 429，响应中包含 retry_after_seconds。参见速率限制。

request_id 是什么，幂等性如何工作？​

request_id 是创建发票时可以附带的可选字段 — 通常是您的内部订单 ID（例如："ORDER-12345"）或一个唯一的随机字符串，只有您的后端和 PayerScan 知道。

为什么要使用？ 如果您的服务器在请求过程中崩溃或超时，您可以安全地使用相同的 request_id 重试。API 保证不会创建重复发票 — 而是返回已存在的发票，响应中标记 "idempotent": true。

将 webhook 与订单匹配： request_id 也会包含在 webhook 回调（completed / expired）中，因此您的后端可以用它来识别该付款属于哪个发票（交易、订单）。

不使用 request_id： 每次 POST 都会创建新发票，即使 body 完全相同。重试时有为同一订单创建重复发票的风险。

amount 使用什么货币？​

amount 字段始终以 USD（美元）为单位。系统会根据实时汇率自动将其转换为相应的加密货币金额。

注意： 汇率来自客户在支付页面选择的四个来源之一 — Binance、Coinbase、CoinGecko 或 CoinMarketCap。

amount 的限制是什么？​

发票的 amount（USD）必须是正数且不能超过 1,000,000。值可以作为字符串或数字发送。

completed_url 和 expired_url 是什么？​

这些是客户浏览器的可选重定向 URL：

  • completed_url — 成功支付后客户将被重定向到此处。
  • expired_url — 发票过期时客户将被重定向到此处。

它们仅用于前端重定向，不能替代 callback_url webhook。

支付与确认​

客户发送错误金额会怎样？​

系统仅在区块链交易完全匹配金额（token_amount）、正确地址且在时间窗口内时才确认。发送过少或过多不会被视为成功支付；发票可能过期，或客户需要创建新发票。

确认需要多长时间？​

通常几秒到几分钟，取决于网络和方式：

  • EVM（BSC、ETH、Polygon 等）：3-15 秒
  • Tron（TRC20）：3-5 秒
  • 交易所充值（Binance、OKX、Bybit 等）：几乎即时
  • Binance Pay：几乎即时

找到匹配交易后，系统立即更新发票并发送 webhook。

发票何时过期？​

默认按 Store 配置（例如 15 分钟）。创建发票时，响应包含 expires_in_minutes。超过该时间后，发票变为 expired 状态，并（如果提供了 callback_url）您会收到 status: "expired" 的 webhook。

发票有哪些可能的状态？​

状态描述
waiting发票已创建，等待客户支付。
completed支付已在区块链上确认。
expired发票过期，未收到支付。

我可以取消发票吗？​

不可以。发票无法通过 API 取消。它们将在配置的时间（expires_in_minutes）后自动过期。如果客户不支付，让它自然过期即可。

Webhook​

哪些事件触发 webhook？​

系统为两类事件发送 webhook：

  • completed — 在区块链上确认匹配的支付。
  • expired — 发票过期且未收到支付。

Webhook 超时时间是多少？​

10 秒。如果商户服务器没有在该时间内返回 HTTP 2xx，请求被视为失败，将被重试。

我需要返回特定的 body 吗？​

不需要。只需返回 HTTP 2xx 状态（例如 200 OK）。body 由您决定（可以为空或 "OK"）。

Webhook 失败后会重试吗？​

会。当返回错误或超时时，系统按以下计划重试：10s → 30s → 30s → 60s → 60s（最多 5 次尝试）。确保端点处理具有幂等性（多次使用同一 trans_id 调用是安全的）。

错误与故障排除​

NO_PAYMENT_METHOD 是什么意思？​

您的 Store 尚未配置支付方式。前往 Store 管理 → 添加至少一个钱包地址或连接一个交易所平台，然后再创建发票。

INSUFFICIENT_BALANCE 是什么意思？​

您的账户余额不足以支付该发票的服务费。费用根据发票的 amount（USD）和您账户的费率计算（折扣可能降低费率）。在 Dashboard 充值后重试。查看错误响应中的 details 字段了解确切的不足金额。

注意： 在免费试用期间（前 7 天），INSUFFICIENT_BALANCE 不会出现 — 所有服务费将被免除。

INVALID_MERCHANT_ID 是什么？​

body 中的 merchant_id 与使用的 API Key 的 Store 不匹配。在 Store 管理中检查 merchant_id，并在请求中发送正确的值。

发票查询返回 404？​

可能原因：(1) trans_id 错误，(2) 发票属于不同的 Store（不同的 API Key），或 (3) 不存在。检查 trans_id 和 API Key。

支付方式​

系统支持哪些支付方式？​

PayerScan 支持多种支付方式：

  • 链上钱包：EVM（BSC、Ethereum、Polygon、Base、Arbitrum）、Tron（TRC20）、Solana
  • 交易所平台：Binance Pay、Binance Deposit、OKX、Bybit、MEXC、Gate.io、Bitget、Upbit、Bitkub

参见网络与代币了解完整列表。

Binance Pay 如何运作？​

Binance Pay 允许客户通过 Binance 支付 — 无 gas 费，即时确认。商户需要在管理页面配置 Binance API Key 和 Secret Key。

交易所平台需要配置什么？​

  1. 在交易所创建 API Key（启用所需权限）
  2. 在管理页面 → 为 Store 配置 API Key、Secret Key 和平台 ID

详情：Binance Pay 设置。

安全​

API Key 应该从前端发送吗？​

不应该。API Key 应该只在服务器（商户的后端）使用。从服务器调用 POST /payment/crypto 和 GET /invoice；前端只接收 url_payment 进行重定向，不需要 API Key。

Callback URL 需要认证吗？​

建议：验证 merchant_id 或 trans_id 与内部数据的一致性，以确保请求合法。使用 HTTPS 防止窃听。

我可以拥有多个 Store 吗？​

可以。每个 Store 有自己的 API Key、merchant_id、支付方式和设置。您可以创建多个 Store 来区分不同的业务或环境（例如，生产 vs. 测试）。