كيف يعمل redirectUrl في صفحة الدفع بالعملات الرقمية
ما هو redirectUrl الذي تعيده واجهة Qvard API، وماذا يرى العميل في تلك الصفحة، وكيف تستخدم الرابط عند الدفع أو في بريد إلكتروني، وما الذي لا يفعله نيابةً عنك.
عند إنشاء دفعة في Qvard تحتوي الاستجابة على حقل واحد يهمّ العميل: redirectUrl، عنوان صفحة دفع تستضيفها Qvard. وهو الجانب الموجَّه للعميل من التكامل بأكمله. يشرح هذا الدليل ما هذا الرابط، وماذا يرى العميل هناك، وكيف تستخدمه عند الدفع أو في بريد إلكتروني، وأي مهام يتركها لك.
ما هو redirectUrl
تنشئ دفعة بطلب POST واحد إلى https://api.qvard.com/api/v1/payment (الترويسة x-api-key، ورقم طلبك كـ id، والمبلغ كـ price بالدولار الأمريكي). الاستجابة 201 بحقلين: id، معرّف الدفعة لدى Qvard، وredirectUrl بالشكل https://my.qvard.com/pay/<id>.
يقود العنوان إلى صفحة دفع مستضافة: صفحة تديرها Qvard لا خادمك. لا تبنيها ولا تستضيفها ولا تصونها. مهمتك أن توصل العميل إلى ذلك العنوان، وأن تعرف النتيجة لاحقًا من الـ webhook.
ماذا يرى العميل
في الصفحة يقوم العميل بما يلي:
- يختار أصلًا وشبكة (أو يجد ما حدّدته مسبقًا بـ
paymentSystemId)؛ - يرى العنوان والمبلغ الدقيق المطلوب إرساله، مع عرض الشبكة بجانب العنوان؛
- يرسل التحويل من محفظته أو منصته.
سعر الصرف في الصفحة ثابت لمدة ساعة، فلا يتحرك المبلغ أثناء دفع العميل. الصفحة نفسها مهما بدا متجرك، وهذا هو المقصود: تحصل على صفحة دفع بالعملات الرقمية تعمل دون أن تبنيها. لرؤيتها قبل التكامل افتح فاتورة تجريبية.
استخدام الرابط عند الدفع
الاستخدام المعتاد إعادة توجيه من الخادم أو زر، في ثلاث خطوات:
- يختار العميل «الدفع بالعملات الرقمية». ينشئ خادمك طلبك الخاص ودفعة Qvard.
- يردّ خادمك بالـ
redirectUrl، كإعادة توجيه HTTP أو كقيمة تستخدمها واجهتك الأمامية للانتقال. - يذهب المتصفح إلى الصفحة؛ ويدفع العميل هناك.
أنشئ الدفعة بعد أن يضغط العميل الزر، لا عند بناء السلة. لا ترسل مفتاح API السري إلى المتصفح أبدًا: المتصفح لا يتلقى إلا الـ redirectUrl. مثال كامل للزر في زر دفع بالعملات الرقمية لمواقع الويب.
استخدام الرابط خارج صفحة الدفع
ولأن الصفحة مستضافة على عنوان بسيط فإن الرابط يعمل أيضًا خارج صفحة دفع ويب:
- في بريد أو ملف PDF للفاتورة، بجانب البيانات المصرفية، ليتمكن عميل الأعمال من اختيار الدفع بالعملات الرقمية (انظر مدفوعات العملات المستقرة لفواتير B2B).
- في محادثة أو رسالة دعم، لدفعة منفردة أنشأتها يدويًا بأدواتك.
- خلف رمز QR، إن كان نظامك يولّده من العنوان.
تعامل مع الرابط على أنه المدخل إلى تلك الدفعة الواحدة. أرسله إلى العميل الذي يخصّه ولا تنشره. روابط الدفع كمنتج مستقل بلا شيفرة قيد التطوير؛ واليوم تنشئ الدفعة عبر الـ API وتشارك العنوان الذي تعيده.
التكرار وإعادة المحاولة وما يحدث بعد الدفع
- الطلب نفسه مرتين. إرسال الـ
idنفسه لطريقة الدفع نفسها يعيد الدفعة الموجودة، فتعطي نقرة مزدوجة أو طلب مُعاد الدفعة نفسها لا ثانية. - لا توجد بعد روابط عودة. بعد الدفع لا يُعاد العميل تلقائيًا إلى موقعك؛ روابط العودة غير متاحة بعد. أعطه صفحة طلب تعرض الحالة الفعلية وتُحدّث نفسها أثناء الانتظار.
- النتيجة هي الـ webhook. يستدعي Qvard الـ callback URL الخاص بك عندما تكون الدفعة مكتملة، مع الـ
idالخاص بك والحالة. يجب أن تردّ نقطتك بـ HTTP 200 بالضبط وأن تكون آمنة إذا نُفّذت مرتين. عودة العميل إلى موقعك ليست دليل دفع. انظر كيف تؤمّن webhook مدفوعات العملات الرقمية.
ما لا يفعله الرابط
لكي لا تبحث عنه:
- لا يخبرك بحالة الدفعة؛ لا يوجد مسار لقراءة دفعة بالـ
id، لذا استخدم الـ webhook وسجلاتك. - لا يعيد العميل إلى موقعك؛ روابط العودة غير متاحة بعد.
- لا يحل محل صفحة طلبك: ما زلت تحتاج إلى صفحة تعرض «بانتظار الدفع» أو «جزئي» أو «مدفوع».
صيغ الطلبات والاستجابات في واجهة API لمدفوعات العملات الرقمية للمطورين، والمسار كاملًا في كيف تقبل مدفوعات العملات الرقمية على موقع ويب.
FAQ
ما هو redirectUrl؟
عنوان صفحة الدفع المستضافة التي تنشئها Qvard لدفعة ما، بالشكل https://my.qvard.com/pay/<id>. ترسل العميل إليه ليدفع.
هل يجب أن أبني صفحة دفع؟
لا. صفحة الدفع تستضيفها Qvard. تنشئ الدفعة فقط عبر الـ API وتعيد توجيه العميل إلى العنوان المُعاد.
هل يمكنني وضع الرابط في بريد إلكتروني؟
نعم. هو عنوان بسيط، فيعمل في بريد فاتورة أو رسالة أو خلف رمز QR. أرسله فقط إلى العميل الذي يخصّه.
كيف أعرف أن العميل دفع؟
من الـ webhook الذي ترسله Qvard عند اكتمال الدفعة. لا يبلغ الرابط بالحالة، ولا توجد بعد روابط عودة.