روابط الدفع: الدليل

ما هو الرابط

رابط الدفع غلاف يحيط بالمدفوعات. يحصل كل عميل يدفع عبره على دفعة خاصة به، في صفحة الدفع المستضافة نفسها التي تُستخدم لأي دفعة أخرى في Qvard.

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

للرابط عملة خاصة به، وهي العملة التي يراها العميل ويدفع بها. كل دفعة تثبّت سعرها لحظة إنشائها. الأسعار الحالية موجودة في صفحة «أسعار العملات».

إنشاء الرابط من لوحة التحكم

في لوحة التحكم افتح قسم «روابط الدفع» واضبط الرابط. الخيارات هي:

• المبلغ: ثابت، أو يُدخله العميل بحد أدنى وحد أقصى.
• حد المدفوعات: بلا حد، أو دفعة واحدة، أو N دفعة.
• المدة: 1 أو 7 أو 30 يومًا، أو بلا مدة.
• بريد المشتري: لا تسأل، أو اختياري، أو إلزامي.

لكل رابط عنوان خاص به: https://qvard.com/l/<slug>. يفتحه العميل، فيختار الرمز المميز والشبكة، ثم يرى صفحة الدفع المعتادة.

يمكن تنزيل الرابط كرمز QR بصيغة PNG، للفواتير المطبوعة والإيصالات والملصقات. يمنحك زر «مشاركة» الرابط لإرساله عبر أي قناة.

رابط لكل عميل عبر API

لمعرفة من يدفع بدقة، أنشئ دفعة لكل عميل عبر API من خادمك، ثم أرسل إلى العميل redirectUrl الموجود في الاستجابة. يجب أن يبقى المفتاح السري (qvard_sk_…) على خادمك فقط.

مثال على الطلب

# Create a payment for one customer
curl -X POST https://api.qvard.com/api/v1/payment \
  -H 'x-api-key: qvard_sk_YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"price":12499.00,"currency":"INR","id":"order-123"}'

# The response contains "data": { "redirectUrl": "https://my.qvard.com/pay/..." }
# Send that redirectUrl to the customer.

// Run on your server only: the secret key must not reach the browser
async function createPaymentLink(orderId, amount) {
  const res = await fetch('https://api.qvard.com/api/v1/payment', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.QVARD_SECRET_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ price: amount, currency: 'INR', id: orderId })
  });
  if (!res.ok) throw new Error('Qvard API error: ' + res.status);
  const payment = await res.json();
  return payment.data.redirectUrl; // send this link to the customer
}

// Usage inside an async handler: const link = await createPaymentLink('order-123', 10);

تتضمن الاستجابة معرّف الدفعة وredirectUrl، مثل https://my.qvard.com/pay/<uuid>. أرسل redirectUrl إلى العميل. القيمة id في الطلب هي رقم طلبك لديك.

لا تضع المفتاح السري (qvard_sk_…) أبدًا في كود يعمل في المتصفح أو في مستودع عام. أنشئ الدفعات من الخادم فقط.

بيع محدود ورابط لمرة واحدة

الرابط لمرة واحدة يقبل دفعة واحدة، وهذا مناسب للفاتورة. أما الرابط ذو الحد N فيقبل N دفعة ثم يتوقف، وهذا مناسب لعرض محدود مثل 100 مقعد.

حالات الرابط

• نشط: يقبل الرابط المدفوعات.
• معطّل: أوقفت الرابط من لوحة التحكم. لا يقبل مدفوعات حتى تفعّله من جديد.
• منتهٍ: انقضت المدة (1 أو 7 أو 30 يومًا).
• مستنفد: بلغ الرابط حد المدفوعات.

الـ webhook للمدفوعات القادمة من الرابط

ترسل المدفوعات المنشأة من رابط الإشعار نفسه (webhook) وتحمل الترويسة X-Qvard-Signature نفسها. يحتوي جسم هذه المدفوعات على حقلين إضافيين اختياريين: paymentLink، وهو slug الرابط، وcustomerEmail، وهو البريد الذي أدخله العميل إذا طلبه الرابط. لا تحمل المدفوعات الأخرى هذين الحقلين.

كيفية التحقق من توقيع webhook

ما الذي لا يخبرك به الرابط

الرابط القابل لإعادة الاستخدام لا يُظهر من دفع. يخبرك الـ webhook بالدفعة، لا بالمشتري.

حقل customerEmail اختياري ولا يُتحقق منه: يكتبه العميل بنفسه ولا يتحقق منه أحد. إذا احتجت إلى معرفة المشتري بدقة، فأنشئ دفعة عبر API لكل مشترٍ.

مرجع API