API 概述与身份验证

QuantaPay 提供了一个简单的类 REST API，用于创建支付、查询交易和以编程方式管理您的账户。

接口地址

所有 API 请求都发送到同一个接口地址：

POST https://cloud.quantapay.app/api.php

内容类型

请求使用 application/x-www-form-urlencoded（标准 HTML 表单编码）。

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

身份验证

每个 API 请求都必须包含您的 API Key 作为 POST 参数。

获取您的 API Key

1. 登录 cloud.quantapay.app
2. 前往 Settings → Account
3. 复制您的 API Key

安全提示：请妥善保管您的 API 密钥。不要在客户端代码或公开仓库中暴露它。

HMAC 签名（可选）

对于 create-checkout-session，您可以添加 HMAC-SHA256 签名验证以防止请求被篡改。

工作原理

1. 构造签名数据字符串：{price}|{currency}|{order_id}|{timestamp}
2. 使用您的 Webhook Secret Key 作为密钥生成 HMAC-SHA256
3. 在请求中包含 signature 和 timestamp

示例（PHP）

$webhook_secret = 'your-webhook-secret-key';
$price = '49.99';
$currency = 'usd';
$order_id = 'ORD-12345';
$timestamp = time();

$sign_data = $price . '|' . $currency . '|' . $order_id . '|' . $timestamp;
$signature = hash_hmac('sha256', $sign_data, $webhook_secret);

// Include in your API request:
// signature={$signature}&timestamp={$timestamp}

示例（Node.js）

const crypto = require('crypto');

const webhookSecret = 'your-webhook-secret-key';
const price = '49.99';
const currency = 'usd';
const orderId = 'ORD-12345';
const timestamp = Math.floor(Date.now() / 1000);

const signData = `${price}|${currency}|${orderId}|${timestamp}`;
const signature = crypto.createHmac('sha256', webhookSecret).update(signData).digest('hex');

注意：时间戳必须在服务器时间的 5 分钟以内，否则请求将被拒绝并返回 "Request expired"。

响应格式

成功

{
  "success": true,
  "response": { ... }
}

错误

{
  "success": false,
  "error_code": "error-code-slug",
  "message": "Human-readable error description"
}

错误码

速率限制

没有严格的速率限制，但过多的请求可能会被限流。对于正常使用（< 100 次请求/分钟），不会触发限流。