Вебхуки

QuantaPay отправляет HTTP POST-запросы на ваш настроенный URL-адрес webhook при возникновении событий оплаты. Это позволяет вашему серверу реагировать на платежи в режиме реального времени.

Настройка

Настройте свой webhook вSettings → Payments → Webhook:

• Webhook URL: Ваша HTTPS-точка доступа (например,https://yoursite.com/webhook/quantapay)
• Webhook Secret Key: Автоматически сгенерированный ключ для проверки полезной нагрузки

Webhook Payload

Когда оплата завершена, QuantaPay отправляет POST-запрос сContent-Type: application/json:

{
  "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"
  }
}

Поля транзакции

Проверка подписи

Поле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..."
    }
  }'

Типы событий

Примечание: Webhook отправляются только длязавершенныхтранзакций (статусC). Срок действия транзакций с истекшим сроком действия и ожидающих транзакций не вызывает веб-хуки.

Рекомендации

1. Быстро отвечайте

Верните HTTP-ответ 200, как только получите веб-хук. Выполняйте ресурсоемкую обработку асинхронно.

2. Идемпотентная обработка

Ваш обработчик веб-хуков должен быть идемпотентным — обработка одного и того же веб-хука дважды не должна приводить к дублированию выполнения. Используйте транзакциюidв качестве ключа дедупликации.

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

3. Проверьте ключ

Всегда проверяйте, что полеkeyсоответствует вашему секретному ключу Webhook перед обработкой.

4. Используйте HTTPS

Всегда используйте HTTPS-endpoint для вашего URL-адреса веб-хука. HTTP-endpoint могут привести к утечке конфиденциальных данных транзакции.

5. Ведите подробный журнал

Регистрируйте все входящие вебхуки для отладки и аудита.

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

6. Предусмотрите корректную обработку ошибок

Если ваш сервер временно недоступен, доставка вебхука может быть пропущена. Используйтеget-checkout-sessionилиget-transactionsAPI в качестве запасного варианта для проверки статуса платежа.