كيف تقبل المدفوعات بالعملات المشفرة على موقع إلكتروني

لقبول العملات المشفرة على موقع إلكتروني تحتاج إلى شيئين على خادمك: استدعاء ينشئ دفعة لطلب، ونقطة نهاية تستقبل النتيجة. يستعرض هذا الدليل الاثنين مع شيفرة تعمل، ثم يتناول الاختبار والحالات الحدّية والأخطاء التي تكلّف التجار المال.

ما الذي تحتاجه قبل أن تبدأ

لا تحتاج إلى تشغيل عقدة بلوكشين ولا إلى حفظ محافظ العملاء. تحتاج إلى:

حساب في البوابة مع مشروع ومفتاح API، وإن أردت تثبيت طريقة الدفع بنفسك فمعرّف تلك الطريقة من مشروعك؛
نقطة نهاية HTTPS عامة على خادمك للـ webhook، محفوظة في المشروع بوصفها callback URL؛
مكان في نظام الطلبات لحفظ حالة الدفعة، مطابَقة برقم طلبك الخاص.

قرّر أمرًا مبكرًا: هل يختار العميل الأصل والشبكة في صفحة الدفع أم تحددهما أنت مسبقًا؟ ترك الاختيار للعميل أبسط ويناسب معظم المتاجر. وإذا أرسلت طريقة دفع فستُفتح الصفحة وهي محددة مسبقًا.

كيف تترابط خطوات المسار كله

هذا هو مسار طلب واحد من مرحلة إتمام الشراء في متجرك حتى حالة «مدفوع»:

يختار العميل «الدفع بالعملات المشفرة» عند إتمام الشراء وينشئ خادمك دفعة لهذا الطلب.
تعيد البوابة رابطًا إلى صفحة الدفع المستضافة لديها.
توجّه العميل إلى تلك الصفحة. يختار أصلًا وشبكة ويرسل المبلغ الدقيق من محفظته.
تراقب البوابة البلوكشين وحين تصبح الدفعة نهائية تستدعي webhook لديك.
يضع webhook علامة «مدفوع» على الطلب ويبدأ تنفيذه.

انتبه إلى ما لا يحدث أبدًا من جهتك: لا تولّد عناوين ولا تفحص كتلًا ولا تقارن مبالغ. شيفرتك تؤدي مهمتين صغيرتين: إنشاء الدفعة والتفاعل مع الحالة النهائية.

الخطوة 1: أنشئ الدفعة من خادمك

استدعِ البوابة من واجهتك الخلفية وليس من المتصفح أبدًا، لأن الطلب يحمل مفتاح API السري. في Qvard هو طلب POST واحد إلى https://api.qvard.com/api/v1/payment مع مفتاحك في الترويسة x-api-key وجسم JSON:

id: رقم طلبك الخاص كنص. يُعاد إليك لاحقًا في webhook، فاستخدم شيئًا يمكنك البحث عنه.
price: المبلغ بالدولار الأمريكي. يدفع العميل ما يعادله بالأصل الذي يختاره.
paymentSystemId (اختياري): معرّف طريقة دفع من مشروعك، لاختيار الأصل والشبكة مسبقًا.

عند النجاح تكون الاستجابة 201 مع id للدفعة وredirectUrl. إعادة إرسال id نفسه لطريقة الدفع نفسها تُرجع الدفعة الموجودة بدل إنشاء نسخة مكررة، فإعادة المحاولة بعد انتهاء المهلة آمنة.

إذا كان الطلب غير صالح تحصل على 400 مع النص Error validation ورسالة لكل حقل؛ والمبلغ الأقل من الحد الأدنى للطريقة المختارة يُرفض بالطريقة نفسها. المفتاح المفقود أو الخاطئ يعيد 401.

Node.jscreate-payment.js

// Called from your checkout handler when the customer chooses "Pay with crypto".
async function createQvardPayment(order) {
  const res = await fetch('https://api.qvard.com/api/v1/payment', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.QVARD_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      id: String(order.id),        // your order number, also used to match the webhook
      price: order.totalUsd        // amount in US dollars
    })
  });

  if (!res.ok) throw new Error('Qvard ' + res.status + ' ' + (await res.text()));

  const { redirectUrl } = await res.json();
  return redirectUrl;              // send the customer to this page
}

الخطوة 2: وجّه العميل إلى صفحة الدفع

وجّه العميل إلى redirectUrl الذي يشبه https://my.qvard.com/pay/<payment id>. في تلك الصفحة يختار الأصل والشبكة ويرى المبلغ الدقيق والعنوان ويدفع من محفظته. سعر الصرف مثبّت لمدة ساعة، فلا يتغير المبلغ أثناء الدفع.

أمران يجب التخطيط لهما:

رحلة العودة. روابط العودة بعد الدفع غير متاحة بعد، فيعود العميل إلى موقعك بنفسه. أعطه صفحة طلب تعرض الحالة الحالية وتُحدَّث عند وصول webhook لديك.
لا تعدّ العودة دفعًا. العميل الذي عاد إلى موقعك لم يدفع بالضرورة. وحده webhook يخبرك بوصول المال.

الخطوة 3: استقبل webhook

عند اكتمال الدفعة يرسل Qvard طلب POST إلى callback URL لمشروعك مع JSON صغير: الـ id الذي أرسلته وحالة الدفعة status. يحمل الطلب مفتاح API الخاص بك في الترويسة x-api-key. هذه ترويسة مصادقة وليست توقيعًا تشفيريًا: قارنها بمفتاحك وارفض كل ما سواها.

طريقة عمل التسليم مهمة لمعالجك:

يعدّ Qvard الـ webhook مسلَّمًا فقط عندما تردّ نقطة نهايتك بالرمز HTTP 200 تحديدًا. أي رمز حالة آخر أو انتهاء المهلة يُعدّ فشلًا.
يُعاد إرسال التسليم الفاشل: خمس محاولات في المجموع، خلال نحو ست دقائق.
لا تُتَّبع إعادات التوجيه، لذا فإن الرد 3xx فشل أيضًا.
يمكنك أيضًا إعادة إرسال إشعار دفعة من لوحة التحكم.

بسبب إعادة المحاولة يجب أن يكون معالجك idempotent: وصول الحدث نفسه مرتين يجب ألا يؤدي إلى شحن الطلب مرتين. يتحقق المثال أدناه من المفتاح ويجد الطلب عبر id الخاص بك ويضع عليه علامة «مدفوع» فقط إذا لم يكن مدفوعًا بعد.

Node.jswebhook.js

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/webhooks/qvard', express.json(), async (req, res) => {
  // Qvard sends your API key in the x-api-key header: compare it with yours.
  const received = Buffer.from(String(req.get('x-api-key') || ''));
  const expected = Buffer.from(process.env.QVARD_API_KEY);
  const valid = received.length === expected.length && crypto.timingSafeEqual(received, expected);
  if (!valid) return res.sendStatus(401);

  const { id, status } = req.body;          // id is the order number you sent
  const order = await db.orders.findById(id);
  if (!order) return res.sendStatus(200);   // unknown order: nothing to retry

  if (status === 'completed' && order.state !== 'paid') {
    await markOrderPaid(order);             // safe to run twice: the check above skips repeats
  }

  return res.sendStatus(200);               // must be exactly 200, otherwise Qvard retries
});

تعامل مع المدفوعات غير المثالية

للدفعة واحدة من أربع حالات:

wait: أُنشئت وتنتظر العميل.
partial: أرسل العميل أقل من المطلوب.
completed: وصل المبلغ كاملًا؛ وهي التي تُطلق webhook.
rejected: رُفضت الدفعة.

قرّر مسبقًا ماذا يفعل متجرك في كل حالة. بالنسبة إلى partial فالاختيار المعتاد إبقاء الطلب مفتوحًا وطلب إرسال الباقي من العميل أو ردّ المبلغ إليه. أبقِ المنطق بسيطًا: ضع علامة «مدفوع» على الطلب عند completed فقط، واعرض على العميل رسالة واضحة في كل حالة أخرى.

اختبر قبل الإطلاق

خطة اختبار قصيرة تلتقط معظم المشكلات:

افتح فاتورة تجريبية لترى صفحة الدفع كما سيراها عميلك.
أنشئ دفعة من خادمك وتأكد من أنك تتلقى redirectUrl.
ادفع مبلغًا حقيقيًا صغيرًا وتأكد من وصول webhook ومن أن الطلب أصبح مدفوعًا.
اجعل نقطة نهايتك تعيد خطأً مرة واحدة، وتأكد أن Qvard يعيد المحاولة وأن معالجك لا يعالج الطلب مرتين.
اسحب مبلغًا صغيرًا من رصيدك إلى محفظتك لتعرف أن المسار كله يعمل.

ليس لدى Qvard بيئة اختبار منفصلة بعد؛ sandbox على خارطة الطريق، فاستخدم مبالغ حقيقية صغيرة في الخطوات من 3 إلى 5.

قائمة التحقق الأمنية

احتفظ بمفتاح API على الخادم فقط. لا تضعه أبدًا في شيفرة الواجهة الأمامية أو في مستودع عام.
قارن الترويسة x-api-key في كل webhook وارفض ما لا يطابق، باستخدام مقارنة بزمن ثابت.
قدّم نقطة النهاية عبر HTTPS وأبقِها سريعة؛ وأنجز العمل البطيء بعد أن تردّ.
طابق المدفوعات بالطلبات عبر id الخاص بك وتجاهل أحداث الطلبات التي لا تعرفها.
سجّل كل webhook مع حالته لتتمكن من حل النزاعات لاحقًا.

المزيد حول هذا الموضوع في كيف تؤمّن webhook مدفوعات العملات المشفرة.

وماذا عن WooCommerce أو Shopify أو منصة أخرى

ينطبق الاستدعاءان نفسهما: شيفرة منصتك تنشئ الدفعة وتستقبل webhook. ليس لدى Qvard إضافة جاهزة بعد، لذا ففي منصة مثل WooCommerce يكون التكامل قطعة شيفرة مخصصة صغيرة أو ساعة عمل لمطوّر، لا خطوة تثبيت بنقرة واحدة. راجع التكاملات لمعرفة الوضع الحالي، وصفحة المطورين لمرجع واجهة API. وإن أردت الصورة العامة أولًا فابدأ بـما هي بوابة الدفع بالعملات المشفرة.

FAQ

هل أحتاج إلى معرفة تطوير البلوكشين؟

لا. ترسل طلب HTTP واحدًا لإنشاء دفعة وتعالج webhook واحدًا. العناوين ومراقبة الشبكة والتأكيدات تتولاها البوابة.

هل يمكنني قبول العملات المشفرة دون كتابة شيفرة؟

ليس بعد مع Qvard. روابط الدفع وغيرها من الطرق دون شيفرة قيد التطوير؛ اليوم يتم التكامل عبر واجهة API، وهو يحتاج إلى مطوّر.

ماذا لو كان خادمي متوقفًا عند اكتمال الدفعة؟

يُعاد إرسال الإشعار خمس مرات خلال نحو ست دقائق. إذا بقي خادمك متوقفًا أطول فأعد إرسال إشعار تلك الدفعة من لوحة التحكم وطابق الطلبات من هناك.

بأي عملة أحدد السعر؟

بالدولار الأمريكي. يدفع العميل ما يعادله بالأصل والشبكة اللذين يختارهما في صفحة الدفع، بسعر صرف مثبّت لمدة ساعة.