跳到主要内容

POST - 创建发票

创建加密支付发票。商户发送金额（USD）、订单信息和回调 URL；系统返回 trans_id 和 url_payment 以将客户重定向到结账页面。

端点​

POST https://api.payerscan.com/payment/crypto

请求头​

请求头必需说明
Content-Type是application/json
x-api-key是商店的 API Key

请求体 (JSON)​

字段类型必需约束说明
merchant_idstring是非空商店的商户代码（必须匹配 API Key）。
amountnumber | string是> 0 且 ≤ 1,000,000支付金额（USD）。例如：100、"100"。
callback_urlstring建议最长 500 字符，有效 URL接收 completed 或 expired 状态 webhook 的 URL。
completed_urlstring否最长 500 字符，有效 URL支付成功后的重定向 URL。
expired_urlstring否最长 500 字符，有效 URL发票过期时的重定向 URL。
namestring否最长 255 字符发票名称/标题。
descriptionstring否最长 1000 字符发票描述。
request_idstring否最长 255 字符商户的订单 ID，用于交叉引用（在响应和 webhook 中返回）。也用于幂等性 — 见下方注意事项。

请求示例​

{
  "merchant_id": "MID-XXXXXXXXXX",
  "amount": 100,
  "name": "Top-up balance",
  "description": "Top-up the balance for username: [USERNAME]",
  "callback_url": "https://your-server.com/webhook/payment",
  "completed_url": "https://your-website.com/thank-you",
  "expired_url": "https://your-website.com/",
  "request_id": "ORDER_123456"
}

响应​

成功 (HTTP 200)​

{
  "status": "success",
  "data": {
    "request_id": "ORDER_123456",
    "trans_id": "TID-ABC123DEF4567890",
    "status": "waiting",
    "amount": "100",
    "url_payment": "https://app.payerscan.com/bill/TID-ABC123DEF4567890",
    "expires_in_minutes": 15
  }
}
字段说明
request_id您在请求中发送的值。
trans_id唯一发票代码，用于查询和 webhook 交叉引用。
status新创建时始终为 "waiting"。
amountUSD 金额（字符串）。
url_payment结账页面 URL — 将客户重定向到此处。
expires_in_minutes发票过期时间（分钟）。

错误 (4xx / 5xx)​

所有错误遵循此格式：

{
  "status": "error",
  "message": "错误描述",
  "error_code": "ERROR_CODE",
  "request_id": "ORDER_123456",
  "details": { }
}
HTTPerror_code说明
400VALIDATION_ERROR无效的 body（缺少必填字段、类型错误、超出约束）。details.errors 有具体信息。
400INVALID_MERCHANT_IDmerchant_id 与商店的 API Key 不匹配。
400NO_PAYMENT_METHOD商店未配置支付方式。创建发票前至少添加一个钱包地址或配置交易所平台。
401MISSING_API_KEY未提供 x-api-key 请求头。
401INVALID_API_KEYAPI key 无效或不存在。
403ACCOUNT_INACTIVE与此 API key 关联的账户已被禁用。
403STORE_INACTIVE与此 API key 关联的商店已被禁用。
402INSUFFICIENT_BALANCE商店余额不足以支付手续费。details 有 current_balance、required_fee、shortage、fee_rate_percent、discount_percent、invoice_amount。
429RATE_LIMIT_EXCEEDED超出请求限制（突发或持续）。有 limit_type、retry_after_seconds。
500INTERNAL_ERROR服务器错误。

错误码详情：API 错误码。

速率限制​

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

超过限制 → HTTP 429，body 有 error_code: "RATE_LIMIT_EXCEEDED"、retry_after_seconds。

注意事项​

  • 支付方式： 商店必须至少配置一个钱包地址或交易所平台（Binance Pay、OKX、Bybit、MEXC、Gate.io、Bitget 等）才能创建发票。如未配置，API 返回 NO_PAYMENT_METHOD 错误。
  • 幂等性： 如果您发送的 request_id 在同一商店中已存在，API 将返回现有发票而不是创建新发票。响应将包含 idempotent: true 以表明这一点。这可防止重试失败请求时创建重复发票。
  • 手续费： 手续费按 amount（USD）计算，从商店余额中扣除。创建发票前确保余额充足。免费试用期间，手续费免除。
  • 回调： 始终发送 callback_url 以接收 completed/expired webhook；否则只能通过 GET https://api.payerscan.com/invoice/:trans_id 检查。
  • request_id： 建议发送以便 webhook 与订单匹配以及支持幂等性。