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

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

الإعداد

قم بتهيئة webhook في الإعدادات → المدفوعات → Webhook:

• Webhook URL: نقطة HTTPS الخاصة بك (مثال: https://yoursite.com/webhook/quantapay)
• Webhook Secret Key: مفتاح مُولَّد تلقائياً للتحقق من الحمولة

حمولة Webhook

عند اكتمال الدفع، يرسل QuantaPay طلب POST مع Content-Type: application/json:

{
  "key": "your-webhook-secret-key",
  "transaction": {
    "id": "197",
    "biz_id": "QP-20260408-560BF",
    "title": "",
    "description": "",
    "from": "0xCustomerWalletAddress",
    "to": "0xYourWalletAddress",
    "hash": "0xBlockchainTransactionHash",
    "amount": "0.025",
    "amount_fiat": "49.99000000",
    "cryptocurrency": "eth",
    "currency": "usd",
    "external_reference": "your-order-id-123",
    "creation_time": "2026-03-08 10:00:00",
    "status": "C",
    "webhook": "1",
    "vat": "0",
    "billing": "",
    "checkout_id": null,
    "type": "2"
  }
}

حقول المعاملة

مطابقة الطلبات باستخدام external_reference

هذه هي الطريقة الموصى بها لربط مدفوعات QuantaPay بطلباتك الخاصة.

عند إنشاء Checkout Session، مرِّر معرّف طلبك في حقل external_reference:

{
  "order_id": "your-order-id-123",
  "external_reference": "your-order-id-123",
  "price": 49.99,
  "currency": "usd"
}

يحفظ QuantaPay هذه القيمة ويُعيدها دون تغيير في حمولة webhook تحت transaction.external_reference. استخدمها للعثور على الطلب الصحيح وإتمامه.

التحقق من التوقيع

يحتوي حقل key في الحمولة على Webhook Secret Key الخاص بك. إذا لم يكن مُهيَّأً، يعود النظام إلى استخدام مفتاح تشفير الحساب. احرص دائماً على تهيئة Webhook Secret Key مخصص.

مثال PHP

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

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

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

$transaction = $payload['transaction'];

// 2. Check payment is complete
if ($transaction['status'] !== 'C') {
    http_response_code(200);
    die('Not completed');
}

// 3. Match your order using external_reference
$your_order_id = $transaction['external_reference'];
$order = find_order($your_order_id);
if (!$order) {
    http_response_code(200);
    die('Order not found');
}

// 4. Verify amount using float comparison (amount_fiat has 8 decimal places)
$paid_amount = floatval($transaction['amount_fiat']);
$expected_amount = floatval($order->total);
if (abs($paid_amount - $expected_amount) > 0.01 || $transaction['currency'] !== $order->currency) {
    http_response_code(200);
    die('Amount mismatch');
}

// 5. Idempotency check — use biz_id as dedup key
if (order_already_fulfilled($transaction['biz_id'])) {
    http_response_code(200);
    die('Already processed');
}

// 6. Mark order as paid
fulfill_order($your_order_id);

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;

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

  // 2. Only process completed payments
  if (transaction.status !== 'C') {
    return res.status(200).send('OK');
  }

  // 3. Match your order using external_reference
  const yourOrderId = transaction.external_reference;
  const bizId = transaction.biz_id; // use as dedup key

  console.log(`Payment completed: ${transaction.amount_fiat} ${transaction.currency}`);
  console.log(`Your order: ${yourOrderId}, QuantaPay ref: ${bizId}`);
  console.log(`TX Hash: ${transaction.hash}`);

  // Fulfill order logic here (use biz_id for idempotency)

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

app.listen(3000);

اختبار cURL

curl -X POST https://yoursite.com/webhook/quantapay \
  -H "Content-Type: application/json" \
  -d '{
    "key": "your-webhook-secret-key",
    "transaction": {
      "id": "197",
      "biz_id": "QP-20260408-560BF",
      "status": "C",
      "amount": "0.025",
      "amount_fiat": "49.99000000",
      "cryptocurrency": "eth",
      "currency": "usd",
      "external_reference": "your-order-id-123",
      "hash": "0xabc123..."
    }
  }'

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

ملاحظة: تُرسَل Webhooks فقط للمعاملات المكتملة (الحالة C). المعاملات المنتهية الصلاحية والمعلَّقة لا تُشغِّل Webhooks.

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

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

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

2. المعالجة الاتحادية

يجب أن يكون معالج webhook لديك متحايداً — معالجة نفس webhook مرتين لا ينبغي أن تسبب تكراراً. استخدم biz_id كمفتاح إزالة التكرار.

if (order_already_fulfilled($transaction['biz_id'])) {
    http_response_code(200);
    die('Already processed');
}

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

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

4. استخدام HTTPS

استخدم دائماً endpoint HTTPS لعنوان URL لـ webhook.

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

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

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

6. التعامل مع الأعطال بأناقة

لا يُعيد QuantaPay تلقائياً إرسال Webhooks الفاشلة. استخدم API get-checkout-session أو get-transactions كبديل للتحقق من حالة الدفع إذا كان خادمك غير متاح مؤقتاً.