跳到主要内容

GET - 获取发票

通过 trans_id 检索发票的当前状态和详情。返回支付状态、金额、代币/网络信息（如果已选择）和交易详情（如果已完成）。仅返回属于与 API Key 关联的商店的发票。

端点​

GET https://api.payerscan.com/invoice/:trans_id

示例: GET https://api.payerscan.com/invoice/TID-ABC123DEF4567890

请求头​

请求头必需说明
x-api-key是商店的 API Key

响应​

成功 (HTTP 200)​

基础响应（始终包含）：

{
  "status": "success",
  "data": {
    "trans_id": "TID-ABC123DEF4567890",
    "request_id": "ORDER_123456",
    "status": "waiting",
    "amount": "100",
    "name": "Top-up balance",
    "description": "Top-up the balance for username: JohnDoe",
    "created_at": 1738742400,
    "expires_at": 1738746000
  }
}

当客户在结账页面选择代币/网络后，data 包含额外字段：

{
  "token_symbol": "USDT",
  "network_symbol": "BSC",
  "token_amount": "100.0026",
  "token_price": "1",
  "to_address": "0xc221460115e2CfCa5bF089A7e647b11cb9631efE"
}

当 status = "completed" 时，data 包含额外字段：

{
  "transaction_hash": "0xd346b32b83b35376d42a2464598fbf565fffb39e...",
  "from_address": "0x8894e0a0c962cb723c1976a4421c95949be2d4e3",
  "fee_amount": "0.2",
  "callback_status": "success"
}

字段说明​

字段说明
trans_id唯一发票代码。
request_id您的订单 ID（如果创建时提供）。
statuswaiting | processing | completed | expired。
amountUSD 金额（字符串）。
name发票名称/标题（如果创建时提供）。
description发票描述（如果创建时提供）。
created_at创建时间（Unix 时间戳，秒）。
expires_at过期时间（Unix 时间戳，秒）。
token_symbol已选代币（如 USDT、BNB）。仅客户选择后显示。
network_symbol网络（如 BSC、TRC20、ETH、BINANCE_PAY）。仅客户选择后显示。
token_amount需转账的加密货币数量。仅客户选择后显示。
token_price选择时的汇率。仅客户选择后显示。
to_address收款钱包地址。仅客户选择后显示。
transaction_hash区块链交易哈希。仅当 status = "completed"。
from_address发送方钱包地址。仅当 status = "completed"。
fee_amount已扣手续费（USD）。仅当 status = "completed"。
callback_statusWebhook 发送状态：success | failed | null。仅当 status = "completed"。

错误 (4xx / 5xx)​

HTTPerror_code说明
400MISSING_TRANS_IDURL 中缺少 trans_id。
400INVALID_TRANS_ID_FORMATtrans_id 格式无效。要求：TID-XXXXXXXXXXXXXXXX（16 个大写字母数字字符）。details 有 trans_id 和 expected_format。
401MISSING_API_KEY未提供 x-api-key 请求头。
401INVALID_API_KEYAPI key 无效或不存在。
403ACCOUNT_INACTIVE与此 API key 关联的账户已被禁用。
403STORE_INACTIVE与此 API key 关联的商店已被禁用。
404INVOICE_NOT_FOUND未找到发票或不属于此商店的 API Key。details.trans_id 包含发送的值。
429RATE_LIMIT_EXCEEDED超出请求限制。
500INTERNAL_ERROR服务器错误。

错误 body 格式：

{
  "status": "error",
  "message": "Invoice not found.",
  "error_code": "INVOICE_NOT_FOUND",
  "details": { "trans_id": "TID-ABC123DEF4567890" }
}

速率限制​

  • 突发： 20 请求/秒（每个 API Key 或 IP）。
  • 持续： 200 请求/分钟（每个 API Key 或 IP）。

使用场景​

  • 轮询： 定期调用 GET https://api.payerscan.com/invoice/:trans_id 更新 UI 状态（当不使用 webhook 作为主要来源时）。
  • 对账： 通过邮件、工单等中的 trans_id 查询发票。
  • 状态显示页面： 客户付款后，从此 API 显示信息。