واجهة API لمدفوعات العملات الرقمية للمطورين

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

ما الذي تغطيه الواجهة

توجد الواجهة العامة على https://api.qvard.com/api/v1 وفيها ثلاثة مسارات:

POST /payment: إنشاء دفعة والحصول على عنوان صفحة الدفع المستضافة.
GET /method/:id/info: التحقق مما إذا كانت طريقة دفع من مشروعك جاهزة لقبول المدفوعات.
POST /payout: إرسال دفعة صادرة إلى عنوان عملة رقمية.

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

المصادقة

يحمل كل طلب مفتاح API الخاص بمشروعك في الترويسة x-api-key. لا توجد رموز للتجديد ولا OAuth. يعيد المفتاح المفقود أو المجهول 401 مع الرسالة error.wrong.api.key.

تعامل مع المفتاح ككلمة مرور: احتفظ به على الخادم، في متغير بيئة أو مدير أسرار، وليس في شيفرة الواجهة الأمامية أو في مستودع عام أبدًا. وهذا المفتاح نفسه هو الذي يعيده Qvard إليك في ترويسة x-api-key الخاصة بالـ webhook، لذا يؤثر أي تسرّب في الاتجاهين.

إنشاء دفعة

يقبل POST /api/v1/payment جسم JSON:

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

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

الاستدعاء idempotent بحسب المعرّف وطريقة الدفع: إرسال الـ id نفسه مرة أخرى لنفس الطريقة يعيد الدفعة الموجودة بدل إنشاء ثانية، لذا فإعادة المحاولة بعد انتهاء المهلة آمنة. لاحظ أن رمز الحالة 201 لا 200.

curlcreate-payment.sh

curl -X POST https://api.qvard.com/api/v1/payment \
  -H "x-api-key: $QVARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "order-1042", "price": 49.9 }'

# 201 Created
# { "id": "6f1c2d3e-...", "redirectUrl": "https://my.qvard.com/pay/6f1c2d3e-..." }

# 401 { "message": "error.wrong.api.key" }
# 400 { "message": "Error validation", "errors": { "price": "..." } }

الأخطاء

للأخطاء شكل واحد، جسم JSON فيه message:

400: فشل الجسم في التحقق. الرسالة Error validation ويربط الكائن errors كل حقل بأول مشكلة فيه، مثل id مفقود أو price ليس رقمًا. وكذلك يُرفض مبلغ أقل من الحد الأدنى للطريقة المختارة.
401: الترويسة x-api-key مفقودة أو مجهولة (error.wrong.api.key).
404: في مسار معلومات الطريقة، معرّف طريقة غير موجود (error.notfound).

سجّل جسم الاستجابة كاملًا عند أي 4xx؛ فالرسالة تسمّي الحقل المطلوب إصلاحه. لا تُعد محاولة 400 أو 401 دون تغيير شيء، لكن أعد محاولة انتهاء المهلة أو 5xx، وهذا آمن بفضل خاصية idempotent أعلاه.

حالات الدفعة والـ webhook

للدفعة إحدى أربع حالات: wait (أُنشئت ولم تُدفع)، partial (وصل أقل من المبلغ كاملًا)، completed (وصل المبلغ كاملًا)، وrejected.

يُرسل الـ webhook عندما تكون الدفعة مكتملة: يجري Qvard طلب POST إلى callback URL الخاص بمشروعك بجسم JSON صغير يحوي الـ id الخاص بك وstatus، ويضع مفتاح API الخاص بك في الترويسة x-api-key. يجب أن تردّ نقطتك بـ HTTP 200 بالضبط؛ أي حالة أخرى أو انتهاء مهلة أو إعادة توجيه تُحسب تسليمًا فاشلًا وتُعاد المحاولة، خمس محاولات في المجموع خلال نحو ست دقائق. الترويسة ترويسة مصادقة لا توقيع تشفيري، لذا قارنها بمفتاحك بزمن ثابت. اجعل المعالج idempotent لأن التسليم قد يصل مرتين.

التفاصيل مع الشيفرة في كيف تؤمّن webhook مدفوعات العملات الرقمية، والمسار كاملًا في كيف تقبل مدفوعات العملات الرقمية على موقع ويب.

التحقق من جاهزية طريقة

يستقبل GET /api/v1/method/:id/info المعرّف الرقمي لطريقة دفع من مشروعك ويردّ 200 بثلاثة حقول:

server: تفاصيل عن حالة الطريقة.
isReady: true عندما تكون الطريقة جاهزة لقبول دفعة.
isActive: true عندما لا تكون الطريقة غير متصلة، حتى لو كانت لا تزال تلحق بالشبكة.

استخدمه قبل عرض أصل وشبكة محددين عند الدفع، مثلًا لإخفاء طريقة غير متاحة مؤقتًا. المعرّف المجهول يعيد 404. وهو اختياري: إن تركت العميل يختار في صفحة الدفع فلا تحتاج إليه.

المدفوعات الصادرة

يرسل POST /api/v1/payout أموالًا من رصيدك إلى عنوان عملة رقمية. جسم JSON يحوي:

id (نص، إلزامي): معرّف الدفعة الصادرة الخاص بك، يُستخدم لإزالة التكرار عند إعادة المحاولة، فإرسال الـ id نفسه مرتين لا يدفع مرتين.
price (رقم، إلزامي): المبلغ بعملة الطريقة الرقمية، لا بالدولار.
methodId (رقم، إلزامي): طريقة الدفع من مشروعك.
address (نص، إلزامي): عنوان الوجهة.
comment (نص، اختياري).

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

ما لا تملكه الواجهة بعد

لتوفّر على نفسك البحث:

لا توجد نقطة نهاية لجلب دفعة بمعرّفها، فاعتمد على الـ webhook وسجلاتك.
لا يوجد توقيع للـ webhook؛ المصادقة هي الترويسة x-api-key.
لا يوجد sandbox: بيئة اختبار منفصلة في خارطة الطريق، لذا استخدم مبالغ حقيقية صغيرة. فاتورة تجريبية تعرض صفحة الدفع دون دفع.
لا توجد روابط عودة بعد الدفع: يعود العميل إلى موقعك من تلقاء نفسه.
لا توجد إضافات جاهزة لمنصات المتاجر، وروابط الدفع قيد التطوير.

للصيغ والأمثلة راجع وثائق المطورين. وللشروط التجارية صفحة الأسعار.

FAQ

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

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

هل إعادة محاولة إنشاء دفعة آمنة؟

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

كيف أعرف نتيجة دفعة؟

من الـ webhook الذي يُرسل عند اكتمال الدفعة. لا يوجد مسار لقراءة دفعة بمعرّفها، لذا احفظ الـ id الذي ترسله وطابقه عند وصول الـ webhook.

هل يوجد sandbox؟

ليس بعد. بيئة اختبار منفصلة مخطط لها. للآن استخدم مبالغ حقيقية صغيرة وفاتورة تجريبية لرؤية صفحة الدفع.