زر دفع بالعملات الرقمية لمواقع الويب
كيف تضيف زر «الدفع بالعملات الرقمية» إلى موقع ويب: لماذا لا يستطيع الزر استدعاء واجهة الدفع مباشرة، والنمط ذو الخطوات الثلاث، وشيفرة عاملة للواجهة الأمامية والخادم، وما يجب حمايته.
إضافة زر «الدفع بالعملات الرقمية» سهلة، لكنه لا يمكن أن يكون مقتطفًا للنسخ واللصق: إنشاء الدفعة يتطلب مفتاح API السري الخاص بك، الذي يجب ألا يصل إلى المتصفح أبدًا. لذا يجب أن يتحدث الزر مع خادمك الخاص، الذي ينشئ الدفعة ويعيد عنوان صفحة الدفع. يعرض هذا الدليل ذلك النمط بشيفرة عاملة والنقاط التي تُبقيه آمنًا.
لماذا لا يوجد بعد زر للنسخ واللصق
يوفر كثير من مزوّدي الدفع زرًا أو أداة قابلة للتضمين. ليس لدى Qvard زر بلا شيفرة بعد: روابط الدفع قيد التطوير. صفحة الدفع المدمجة جاهزة كأداة لموقعك. حزم SDK جاهزة. اليوم يتم التكامل عبر الـ API، وتُوثَّق الواجهة بـمفتاح سري في ترويسة Authorization: Bearer.
يستطيع هذا المفتاح إنشاء مدفوعات لمشروعك، لذا يجب أن يبقى على خادمك. الزر الذي يحمل المفتاح في شيفرة الواجهة الأمامية سيسلّمه لكل زائر. هذا ليس قيدًا يجب الالتفاف عليه؛ إنه سبب وجود خطوة الخادم في النمط أدناه.
النمط: الزر ونقطة نهايتك وصفحة الدفع
ثلاث خطوات تصنع زرًا يعمل:
- الزر يرسل طلبًا إلى نقطة نهاية على خادمك أنت، يذكر ما يريد الزائر شراءه (منتج، خطة)، لا كم يكلّف.
- نقطة نهايتك تبحث عن السعر وتنشئ سجل طلبك الخاص وتستدعي Qvard: طلب
POSTواحد إلىhttps://api.qvard.com/api/v1/paymentمع المفتاح في الترويسةAuthorization: Bearerوجسم JSON فيه رقم طلبك كـidوالمبلغ كـpriceبالدولار الأمريكي. الاستجابة201معredirectUrl. - المتصفح يُعاد توجيهه إلى ذلك الـ
redirectUrl، صفحة الدفع المستضافة لدى Qvard، حيث يختار الزائر أصلًا وشبكة ويدفع من محفظة.
لا شيء سري يمسّ الصفحة، وصفحة الدفع نفسها مستضافة لدى Qvard، فلا تبني صفحة دفع بالعملات الرقمية.
الواجهة الأمامية: زر وإعادة توجيه
يحتاج الزر إلى نحو خمسة عشر سطرًا. يعطّل نفسه أثناء الطلب، ويرسل معرّف المنتج، وعند النجاح يأخذ المتصفح إلى العنوان المُعاد. وعند الفشل يعيد تفعيل نفسه ويعرض رسالة، ليتمكن الزائر من المحاولة مجددًا.
تذكّر قاعدة واحدة: يرسل المتصفح ما يُشترى، لا كم يكلّف أبدًا. لو جاء المبلغ من الصفحة لاستطاع أي شخص فتح أدوات المطور وتحويل خطة بـ 49 دولارًا إلى دفعة بدولار واحد.
<button id="pay-crypto" data-product="pro-plan">Pay with crypto</button>
<script>
document.getElementById('pay-crypto').addEventListener('click', async (event) => {
const button = event.currentTarget;
button.disabled = true;
try {
// Send only WHAT is being bought; the server decides the price.
const res = await fetch('/api/crypto-checkout', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ product: button.dataset.product })
});
if (!res.ok) throw new Error('checkout failed');
const { redirectUrl } = await res.json();
window.location.assign(redirectUrl); // the Qvard hosted payment page
} catch (e) {
button.disabled = false;
alert('Could not start the payment. Please try again.');
}
});
</script>الخادم: السعر والطلب والدفعة
تقوم نقطة النهاية في المثال بأربعة أمور:
- تبحث عن السعر في جدول على الخادم وترفض المنتجات المجهولة.
- تنشئ طلبك الخاص وتستخدم رقمه كـ
idللدفعة. بهذا يجد الـ webhook الطلب لاحقًا. - تستدعي Qvard وتعيد إلى المتصفح الـ
redirectUrlفقط. الرد400(«Error validation»، مع رسالة لكل حقل) يعني أن الجسم خاطئ؛ و401يعني أن المفتاح خاطئ. لا يجوز إعادة أيٍّ منهما دون تغيير. - آمنة عند التكرار. إرسال الـ
idنفسه لطريقة الدفع نفسها يعيد الدفعة الموجودة، فلا ينشئ زائر نقر مرتين دفعتين.
أضف تحديدًا لمعدل الطلبات إلى نقطة النهاية حتى لا يستطيع أحد إنشاء آلاف الطلبات غير المدفوعة، واشترط مستخدمًا مسجّل الدخول أو captcha إن احتاج منتجك.
import express from 'express';
import crypto from 'node:crypto';
const app = express();
const PRICES_USD = { 'pro-plan': 49 }; // prices live on the server, never in the browser
app.post('/api/crypto-checkout', express.json(), async (req, res) => {
const price = PRICES_USD[req.body.product];
if (!price) return res.sendStatus(400);
const orderId = await db.orders.create({ product: req.body.product, amountUsd: price }); // your own order number
const response = await fetch('https://api.qvard.com/api/v1/payment', {
method: 'POST',
headers: { Authorization: 'Bearer ' + process.env.QVARD_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ id: String(orderId), price })
});
if (response.status !== 201) return res.sendStatus(502);
const { redirectUrl } = await response.json();
res.json({ redirectUrl });
});بعد النقر: الـ webhook يقرر
إعادة توجيه الزائر إلى صفحة الدفع تبدأ الدفعة؛ ولا تُنهيها. عند اكتمال الدفعة يستدعي Qvard الـ callback URL المحفوظ في مشروعك مع الـ id الخاص بك والحالة completed. عندها فقط امنح الوصول أو ضع علامة «مدفوع» على الطلب. يجب أن تردّ نقطة النهاية بـ HTTP 200 بالضبط وأن تكون آمنة إذا نُفّذت مرتين؛ انظر كيف تؤمّن webhook مدفوعات العملات الرقمية.
لا توجد بعد روابط عودة بعد الدفع، لذا يعود الزائر إلى موقعك من تلقاء نفسه. أعطه صفحة تعرض حالة الطلب الفعلية وتُحدّث نفسها أثناء الانتظار، لا صفحة شكر تفترض النجاح.
أسعار ثابتة ومبالغ متغيرة وما بعد ذلك
- الأسعار الثابتة (خطط، منتجات) هي الحالة السهلة: يحتفظ بها الجدول على الخادم.
- المبالغ المتغيرة (تبرعات، شحن رصيد) تحتاج إلى تحقق على الخادم: حد أدنى وحد أقصى وفحص للرقم. يُرفض المبلغ الأقل من الحد الأدنى لطريقة الدفع المختارة بـ
400. - عدة أزرار تتشارك نقطة النهاية نفسها؛ ويختلف فقط معرّف المنتج.
الشرح الكامل في كيف تقبل مدفوعات العملات الرقمية على موقع ويب، والواجهة نفسها في واجهة API لمدفوعات العملات الرقمية للمطورين. فاتورة تجريبية تُظهر الصفحة التي يقود إليها الزر؛ والشروط التجارية في صفحة الأسعار.
FAQ
هل يمكنني وضع مفتاح API الخاص بـ Qvard في شيفرة الزر؟
لا. يستطيع المفتاح إنشاء مدفوعات لمشروعك ويجب أن يبقى على خادمك. يجب أن يستدعي الزر نقطة نهايتك الخاصة التي تستدعي Qvard.
هل توجد أداة قابلة للتضمين أو زر بلا شيفرة؟
نعم، صفحة الدفع المدمجة جاهزة كأداة لموقعك. زر بلا شيفرة ليس متاحًا بعد: روابط الدفع قيد التطوير. حزم SDK جاهزة. اليوم يستخدم التكامل الـ API مع نقطة نهاية صغيرة على الخادم.
من أين يجب أن يأتي السعر؟
من خادمك، لا من المتصفح أبدًا. يرسل الزر فقط ما يُشترى، ويقرر الخادم السعر بالدولار الأمريكي.
كيف أعرف أن العميل دفع؟
من الـ webhook الذي يرسله Qvard عند اكتمال الدفعة. عودة الزائر إلى الموقع ليست دليل دفع.
