خطافات الويب (Webhooks)

ترسل QuantaPay طلبات HTTP POST إلى عنوان URL الخاص بـ webhook الذي قمت بتكوينه عند وقوع أحداث الدفع. يتيح ذلك لخادمك التفاعل مع المدفوعات في الوقت الفعلي.

الإعداد

قم بتكوين webhook الخاص بك فيالإعدادات ← المدفوعات ← Webhook:

• عنوان URL الخاص بـ Webhook: نقطة نهاية HTTPS الخاصة بك (على سبيل المثال،https://yoursite.com/webhook/quantapay)
• مفتاح سري لـ Webhook: مفتاح تم إنشاؤه تلقائيًا للتحقق من الحمولة

حمولة Webhook

عند إكمال الدفع، ترسل 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. إذا لم يتم تكوين مفتاح سري للـ Webhook، فسيعود النظام إلى استخدام مفتاح تشفير حسابك بدلاً من ذلك. تحقق من أن هذه القيمة تطابق السر المخزن لديك لتأكيد أن الـ 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..."
    }
  }'

أنواع الأحداث

ملاحظة: يتم إرسال Webhooks فقط للمعاملاتcompleted(الحالةC). المعاملات منتهية الصلاحية والمعلقة لا تؤدي إلى تشغيل webhooks.

أفضل الممارسات

1. الاستجابة بسرعة

أرجع استجابة HTTP 200 بمجرد تلقي الـ webhook. قم بالمعالجة الثقيلة بشكل غير متزامن.

2. معالجة متكررة

يجب أن يكون معالج الـ webhook الخاص بك متكررًا - معالجة نفس الـ webhook مرتين يجب ألا تتسبب في تكرار التنفيذ. استخدم معاملةidكمفتاح لإزالة التكرار.

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

3. تحقق من المفتاح

تحقق دائمًا من أن الحقلkeyيطابق مفتاح Webhook السري الخاص بك قبل المعالجة.

4. استخدم HTTPS

استخدم دائمًا نقطة نهاية HTTPS لعنوان URL الخاص بـ webhook. قد تؤدي نقاط نهاية HTTP إلى تسريب بيانات المعاملات الحساسة.

5. تسجيل كل شيء

سجّل جميع الـ webhooks الواردة لأغراض التصحيح والتدقيق.

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

6. معالجة حالات الفشل بسلاسة

إذا كان الخادم الخاص بك متوقفًا مؤقتًا، فقد يتم تفويت تسليم الـ webhook. استخدمget-checkout-sessionأوget-transactionsAPI كحل بديل للتحقق من حالة الدفع.