Skip to main content
POST
دفع فاتورة

نظرة عامة

يدفع فاتورة واحدة من عملية اكتشاف بحالة READY. تختار billId واحدًا من bills[] الخاصة بتلك المعاملة؛ ثم تحمل المعاملة نفسها الدفعة حتى تبلغ حالة نهائية.
200 إقرار بالاستلام، وليس نتيجة. فهو يعني أن الدفعة قُبِلت وأنها الآن قيد التنفيذ. أما ما إذا كانت الأموال قد تحركت فعلًا فلا يُعرف إلا من status الخاص بالمعاملة — استعلم دوريًا حتى تبلغ SUCCESS أو FAILED أو REFUNDED.
هذا هو الاستدعاء الذي يحرّك الأموال. كل ما تحتاجه من جانبك — سجل الطلب والمبلغ وتفويض عميلك — ينبغي أن يكون محفوظًا بالفعل قبل أن ترسله.

متن الطلب

string
مطلوب
عملية الاكتشاف المطلوب الدفع مقابلها. يجب أن تكون سلسلة سداسية عشرية من 24 حرفًا بأحرف صغيرة، ويجب أن تكون المعاملة حاليًا بحالة READY.
string
مطلوب
قيمة billId لأحد العناصر في bills[] الخاصة بتلك المعاملة. 100 حرف كحد أقصى.انسخها من الاستجابة — لا تُنشئها بنفسك.
string
مطلوب
مرجع جديد لهذه الدفعة. 100 حرف كحد أقصى، وفريد بين معاملاتك النشطة لدى هذا الشريك.يجب أن يختلف عن ref الذي استخدمته للاكتشاف؛ إعادة استخدام تلك القيمة تُجيب بـ 403 DUPLICATED_REF.
تحتفظ المعاملة بالمرجع ref الذي أُنشئت به. مرجع الاكتشاف الأصلي ذاك هو ما تُعيده هذه الـ endpoint، وما يبحث عنه الحصول على المعاملة بالمرجع، وما يظهر على المعاملة من الآن فصاعدًا.

الاستجابة

boolean
مطلوب
true عندما تُقبَل الدفعة.
object
مطلوب
object
مطلوب
string
مطلوب
معرّف الربط، يُرسل أيضًا في ترويسة الاستجابة X-Request-Id.

الأمثلة

استجابة النجاح

بمجرد أن تبلغ المعاملة الحالة SUCCESS، يُرجع الحصول على المعاملة بالمعرّف الحقلين operationId وreceiptUrl إلى جانب selectedBill وtotal.

استجابات الخطأ

المتن لم يطابق المخطط.
الأسباب الشائعة: transactionId ليس من 24 حرفًا سداسيًا عشريًا، أو غياب billId، أو غياب ref، أو ref أطول من 100 حرف.ما العمل: صحّح الطلب. لا تعد إرساله دون تغيير أبدًا.
المفتاح غائب أو مرفوض.
ما العمل: تحقق من المفتاح عبر التحقق من مفتاح API. لم يُخصم أي مبلغ.
المرجع ref مستخدم بالفعل مع هذا الشريك.
السبب الأكثر شيوعًا هو إعادة استخدام مرجع ref الاكتشاف في الدفع. أرسل قيمة مختلفة، مثلًا pay- قبل معرّف طلبك.ما العمل: قبل إعادة المحاولة، تحقق من الحالة الحالية للمعاملة عبر الحصول على المعاملة بالمعرّف. إذا كانت بالفعل PROCESSING، فقد نفذت دفعتك ولا شيء لإعادة إرساله.
المعاملة غير موجودة ضمن حسابك، أو أنها ليست في حالة قابلة للدفع، أو أن billId ليس من ضمن فواتيرها.
الحالات الثلاث كلها تُجيب بـ 404 — بما في ذلك معاملة تعود إلى شريك آخر، حتى لا تؤكد واجهة API أبدًا وجود معاملة تخص غيرك.ما العمل: أعد قراءة المعاملة. إذا لم تعد status هي READY، فقد بدأت الدفعة بالفعل؛ استعلم عنها دوريًا بدلًا من إرسال دفعة أخرى.
هذه الفاتورة بعينها سُدِّدت بالفعل.
ما العمل: تعامل معها كنتيجة ناجحة تملكها بالفعل. ابحث عن المعاملة المدفوعة في قائمة المعاملات واستخدم إيصالها. لا تحمّل عميلك المبلغ مرتين.
دفعة أخرى للفاتورة نفسها لم تنتهِ بعد.
ما العمل: استعلم دوريًا عن المعاملة الجارية بالفعل. إرسال هذا مجددًا لن يجعلها تنتهي أسرع.
تعذّر الوصول إلى مُصدِر الفواتير، أو أنه موقوف حاليًا.
ما العمل: لم يُخصم أي مبلغ. لا تزال عملية الاكتشاف بحالة READY، لذا يمكنك دفع billId نفسه لاحقًا — بالمرجع ref نفسه، فهو لم يُستهلك قط.
لم نتمكن من التحقق من مفتاحك في الوقت المحدد. مفتاحك ليس هو المشكلة.
ما العمل: انتظر مدة Retry-After (5 ثوانٍ) وأعد إرسال الطلب نفسه. لم يصل الطلب أبدًا إلى مسار الدفع، لذا فإعادة إرساله آمنة.
واجهة Bill Payment API في صيانة مُخطط لها.
ما العمل: التزم بـ Retry-After وأعد المحاولة.
حدث خلل من جانبنا.
ما العمل: لا تعد إرسال الدفعة. اقرأ المعاملة أولًا — إذا كانت PROCESSING، فالدفعة قيد التنفيذ. تواصل مع الدعم مع ذكر requestId إذا كانت الحالة غير واضحة.

ما الذي تدفعه

كل فاتورة في عملية اكتشاف تحمل حقولها المالية الخاصة.الرسوم نسبة مئوية من المبلغ، محصورة بين حد أدنى وحد أقصى، تُضبط لكل مُصدِر فاتورة على حدة:بما أن 0.5% من فاتورة اعتيادية تقل كثيرًا عن الحد الأدنى، تُحتسب معظم المدفوعات بالحد الأدنى تمامًا. هذه القيم إعدادات قابلة للتعديل، لذا اقرأ fee من الاستجابة بدلًا من إعادة حسابه. يظهر total على المعاملة بمجرد اختيار فاتورة.بالنسبة لفاتورة ADE البالغة 443.39 دينار جزائري أعلاه: نسبة 0.5% تساوي 2.22، وهي أقل من الحد الأدنى البالغ 30 دينارًا، لذا تكون قيمة fee هي 30.00 وقيمة total هي 473.39.

قبل الاستدعاء

1

احفظ سجلك الخاص أولًا

اكتب طلبك — العميل وtransactionId وbillId وamount وfee وtotal والمرجع ref الذي أنت على وشك استخدامه — قبل أن يغادر الطلب عمليتك. إذا ضاعت الاستجابة، فذلك السجل هو ما يمكّنك من العثور على الدفعة مجددًا.
2

أكّد المبلغ مع عميلك

يأتي amount وfee من عملية الاكتشاف. اعرض قيمة total التي أنت على وشك خصمها، لا تقديرًا تقريبيًا.
3

أرسل الدفعة

استدعاء واحد، بمرجع ref جديد لدى هذا الشريك.
4

استعلم دوريًا حتى الحالة النهائية

SUCCESS أو FAILED أو REFUNDED. تعامل مع UNKNOWN على أنها «تابع الاستعلام»، لا على أنها فشل.الاستعلام الدوري عن الحالة

الحواجز التي تحميك

ثلاث قواعد تمنع تحرك المال نفسه مرتين. الثلاث جميعها تُجيب قبل خصم أي مبلغ.
لا واحدة من هذه الثلاث سبب لإعادة المحاولة بمرجع ref مختلف. كل منها يعني أن العمل إما أُنجز بالفعل أو أنه قيد التنفيذ بالفعل — ابحث عنه بدلًا من إرساله من جديد.

أفضل الممارسات

اكتب قبل أن ترسل

احفظ سجل طلبك، بما فيه ref، قبل إرسال الطلب. عندها تصبح الاستجابة الضائعة قابلة للاسترجاع.

مرجع واحد لكل استدعاء

استخدم ref مختلفًا للاكتشاف وآخر للدفع. يكفي وضع disc- وpay- قبل معرّف طلبك.

لا تعد الإرسال عند انتهاء المهلة أبدًا

اقرأ المعاملة أولًا. انتهاء مهلة الشبكة لا يعني أن الدفعة لم تحدث.

اخصم انطلاقًا من total

اخصم من عميلك قيمة total التي أرجعتها واجهة API، لا قيمة حسبتها بنفسك.

Endpoints ذات الصلة

اكتشاف الفواتير

اعثر على ما هو قابل للدفع

الحصول على المعاملة بالمعرّف

استعلم دوريًا عن النتيجة

تنزيل الإيصال

إثبات الدفع

الحصول على المعاملة بالمرجع

استعد استجابة ضائعة

دفع الفواتير

الشرح الكامل

الاستعلام الدوري عن الحالة

مُستعلِم دوري بجودة الإنتاج