api

Webhooks

当支付事件发生时，QuantaPay 会向您配置的 webhook URL 发送 HTTP POST 请求。这使您的服务器能够实时响应支付事件。

更新于: 2026/3/9

当支付事件发生时，QuantaPay 会向您配置的 webhook URL 发送 HTTP POST 请求。这使您的服务器能够实时响应支付事件。

设置

在 Settings → Payments → Webhook 中配置您的 webhook：

Webhook URL：您的 HTTPS 端点（例如 https://yoursite.com/webhook/quantapay）
Webhook Secret Key：自动生成的密钥，用于载荷验证

Webhook 载荷

当支付完成时，QuantaPay 会发送一个 Content-Type: application/json 的 POST 请求：

{
  "key": "your-webhook-secret-key",
  "transaction": {
    "id": "123",
    "title": "Payment #ORD-12345",
    "description": "",
    "from": "0xCustomerWalletAddress",
    "to": "0xYourWalletAddress",
    "hash": "0xBlockchainTransactionHash",
    "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": "",
    "billing": "",
    "checkout_id": "cs-cs_a1b2c3d4e5f6a1b2c3d4"
  }
}

交易字段

字段	类型	描述
`id`	string	QuantaPay 中的交易 ID。
`title`	string	交易标题/描述。
`from`	string	客户的钱包地址（发送方）。
`to`	string	您的钱包地址（接收方）。
`hash`	string	区块链交易哈希。
`amount`	string	加密货币金额。
`amount_fiat`	string	法定货币金额。
`cryptocurrency`	string	加密货币代码（例如 `btc`、`eth`、`usdt`）。
`currency`	string	法定货币代码（例如 `usd`、`eur`）。
`external_reference`	string	外部引用（例如 WordPress 订单数据）。
`creation_time`	string	交易创建时间戳。
`status`	string	交易状态：`C`（已完成）。
`checkout_id`	string	关联的结账会话 ID（格式：`cs-cs_xxxxx`）。

签名验证

载荷中的 key 字段包含您的 Webhook Secret Key。如果未配置 Webhook Secret Key，系统会回退使用您账户的加密密钥。验证此值与您存储的密钥是否匹配，以确认 webhook 的真实性。

PHP 示例

$payload = json_decode(file_get_contents('php://input'), true);

$webhook_secret = 'your-webhook-secret-key'; // From Settings

if ($payload['key'] !== $webhook_secret) {
    http_response_code(401);
    die('Invalid webhook signature');
}

// Process the payment
$transaction = $payload['transaction'];
$order_id = $transaction['title'];
$amount = $transaction['amount_fiat'];
$status = $transaction['status'];

if ($status === 'C') {
    // Payment completed — fulfill the order
    fulfill_order($order_id, $amount);
}

http_response_code(200);
echo 'OK';

Node.js 示例

const express = require('express');
const app = express();
app.use(express.json());

const WEBHOOK_SECRET = 'your-webhook-secret-key';

app.post('/webhook/quantapay', (req, res) => {
  const { key, transaction } = req.body;

  // Verify webhook authenticity
  if (key !== WEBHOOK_SECRET) {
    return res.status(401).send('Invalid signature');
  }

  // Process completed payment
  if (transaction.status === 'C') {
    console.log(`Payment received: ${transaction.amount_fiat} ${transaction.currency}`);
    console.log(`Crypto: ${transaction.amount} ${transaction.cryptocurrency}`);
    console.log(`TX Hash: ${transaction.hash}`);

    // Fulfill order logic here
  }

  res.status(200).send('OK');
});

app.listen(3000);

cURL 测试

# Simulate a webhook (for testing)
curl -X POST https://yoursite.com/webhook/quantapay \
  -H "Content-Type: application/json" \
  -d '{
    "key": "your-webhook-secret-key",
    "transaction": {
      "id": "123",
      "status": "C",
      "amount": "0.025",
      "amount_fiat": "49.99",
      "cryptocurrency": "eth",
      "currency": "usd",
      "hash": "0xabc123..."
    }
  }'

事件类型

状态	事件	描述
`C`	支付完成	付款已在区块链上获得足够的确认。

注意：Webhook 仅在交易完成（状态 C）时发送。过期和待处理的交易不会触发 webhook。

最佳实践

1. 快速响应

收到 webhook 后立即返回 HTTP 200 响应。将耗时处理放在异步流程中执行。

2. 幂等处理

您的 webhook 处理程序应该是幂等的 -- 重复处理同一个 webhook 不应导致重复发货。使用交易 id 作为去重键。

// Check if already processed
if (order_already_fulfilled($transaction['id'])) {
    http_response_code(200);
    die('Already processed');
}

3. 验证密钥

在处理之前始终验证 key 字段是否与您的 Webhook Secret Key 匹配。

4. 使用 HTTPS

始终为 webhook URL 使用 HTTPS 端点。HTTP 端点可能会泄露敏感的交易数据。

5. 记录所有日志

记录所有传入的 webhook，用于调试和审计。

error_log('QuantaPay Webhook: ' . json_encode($payload));

6. 优雅处理故障

如果您的服务器暂时不可用，webhook 投递可能会丢失。使用 get-checkout-session 或 get-transactions API 作为备用方案来检查支付状态。