api

交易 API

交易 API 涵盖完整的支付生命周期：创建结账会话、查询交易状态以及验证区块链确认。

更新于: 2026/3/9

交易 API 涵盖完整的支付生命周期：创建结账会话、查询交易状态以及验证区块链确认。

支付流程概览

┌─────────────┐    ┌──────────────┐    ┌──────────────┐    ┌───────────────┐
│ Your Server │───>│ Create       │───>│ Customer     │───>│ Blockchain    │
│             │    │ Checkout     │    │ Pays on      │    │ Confirms      │
│ POST api.php│    │ Session      │    │ Payment Page │    │ Transaction   │
└─────────────┘    └──────────────┘    └──────────────┘    └───────────────┘
                         │                                        │
                         │ payment_url                             │
                         ▼                                        ▼
                   ┌──────────────┐                         ┌───────────────┐
                   │ Redirect     │                         │ Webhook POST  │
                   │ Customer     │                         │ to Your Server│
                   │ to pay.php   │                         │               │
                   └──────────────┘                         └───────────────┘
  1. 您的服务器调用 create-checkout-session，传入支付金额和货币。
  2. 您会收到一个 payment_url，将客户重定向到该地址。
  3. 客户选择加密货币，扫描二维码并发送付款。
  4. QuantaPay 监控区块链并等待确认。
  5. 确认完成后，QuantaPay 会向您的服务器发送 webhook 和/或将客户重定向。

create-checkout-session

创建新的支付会话。返回一个支付 URL，用于将客户重定向到支付页面。

请求

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=create-checkout-session" \
  -d "api-key=YOUR_API_KEY" \
  -d "price=49.99" \
  -d "currency=USD"

参数

参数类型必需描述
pricenumber是以指定货币计价的支付金额。
currencystring是ISO 4217 货币代码（例如 USD、EUR、GBP）。
order_idstring否您的内部订单 ID，用于参考。
redirectstring否支付成功后重定向客户的 URL。
cancel_urlstring否客户取消支付时重定向的 URL。
notestring否附加到交易的内部备注。
itemsJSON string否商品行项目数组（见下文）。
customerJSON string否客户信息对象。
signaturestring否用于防篡改的 HMAC-SHA256 签名。
timestampinteger否Unix 时间戳（提供签名时必须同时提供）。
external_referencestring否来自 WordPress 插件的加密引用。
pluginstring否来源插件标识符（例如 woo、edd）。

商品格式

[
  {
    "name": "Product Name",
    "qty": 2,
    "price": 24.99,
    "image": "https://example.com/product.jpg"
  }
]
  • 每个会话最多 50 个商品。
  • name：最多 200 个字符。
  • image：必须是 HTTP 或 HTTPS URL，最多 500 个字符。

响应

{
  "success": true,
  "response": {
    "session_id": "cs_a1b2c3d4e5f6a1b2c3d4",
    "payment_url": "https://cloud.quantapay.app/pay.php?session=cs_a1b2c3d4e5f6a1b2c3d4",
    "expires_at": "2026-03-08T11:00:00+00:00"
  }
}
  • session_id：唯一会话标识符（格式：cs_ + 24 个十六进制字符）。
  • payment_url：将客户重定向到此 URL 以完成支付。
  • expires_at：ISO 8601 时间戳。会话在 60 分钟后过期。

错误响应

消息原因
Missing required fields: price, currencyprice 为 0/缺失或 currency 为空。
Invalid signatureHMAC 签名验证失败。
Request expired时间戳与服务器时间相差超过 5 分钟。
Failed to create checkout session数据库错误。

get-checkout-session

查询结账会话的当前状态。

请求

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

参数

参数类型必需描述
session_idstring是结账会话 ID（以 cs_ 开头）。

响应

{
  "success": true,
  "response": {
    "session_id": "cs_a1b2c3d4e5f6a1b2c3d4",
    "status": "paid",
    "price": 49.99,
    "currency": "usd",
    "order_id": "ORD-12345",
    "created_at": "2026-03-08T10:00:00+00:00",
    "expires_at": "2026-03-08T11:00:00+00:00",
    "paid_at": "2026-03-08T10:15:23+00:00"
  }
}

会话状态

状态描述
active会话已打开，正在等待付款。
paid已收到付款并在区块链上确认。
expired会话在未收到付款的情况下过期（60 分钟后）。
cancelled会话在收到付款之前被取消。

get-transactions

查询分页的交易列表。适用于对账和报表。

请求

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

参数

所有参数均为可选：

参数类型描述
paginationinteger页码（从 0 开始）。每页最多返回 100 条交易。
searchstring按交易 ID、哈希、金额或描述搜索。
statusstring按状态筛选：C（已完成）、P（待处理）、X（金额不足）、E（已过期）。
cryptocurrencystring按加密货币代码筛选（例如 btc、eth）。
date_rangearray日期范围筛选，两个元素的数组：date_range[0]=2026-01-01&date_range[1]=2026-03-01。
checkout_idstring按结账/支付按钮 ID 筛选。

响应

返回交易对象数组：

{
  "success": true,
  "response": [
    {
      "id": "123",
      "title": "Payment #ORD-12345",
      "description": "",
      "from": "0xCustomerAddress...",
      "to": "0xYourAddress...",
      "hash": "0xTransactionHash...",
      "amount": "0.025",
      "amount_fiat": "49.99",
      "cryptocurrency": "eth",
      "currency": "usd",
      "external_reference": "",
      "creation_time": "2026-03-08 10:00:00",
      "status": "C",
      "webhook": "1",
      "vat": ""
    }
  ]
}

交易状态

代码状态描述
C已完成付款已在区块链上确认。
P待处理等待付款或区块链确认。
X金额不足已收到付款但金额低于所需金额。
E已过期支付窗口在未收到足够付款的情况下过期。
R已退款付款已退还。

get-transaction

根据 ID 获取单笔交易的详细信息。

请求

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

参数

参数类型必需描述
transaction_idinteger是交易 ID。

响应

返回单个交易对象（格式与 get-transactions 相同）。

check-transaction

手动触发特定交易的区块链确认检查。

请求

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

参数

参数类型必需描述
transactionJSON string是要检查的交易对象（由 get-transaction 返回的格式）。

响应

返回更新后的交易对象，包含当前确认状态。如果达到所需的确认次数，交易状态将变为 C（已完成）。

注意：在正常操作中通常不需要此功能。QuantaPay 会通过其定时任务系统自动检查确认。仅在需要强制立即检查时使用。

下一篇 → API 概述与身份验证