دفع فاتورة
دفع الفواتير
دفع فاتورة
ادفع إحدى الفواتير التي عثرت عليها عملية اكتشاف
POST
دفع فاتورة
نظرة عامة
يدفع فاتورة واحدة من عملية اكتشاف بحالةREADY. تختار billId واحدًا من bills[] الخاصة بتلك المعاملة؛ ثم تحمل المعاملة نفسها الدفعة حتى تبلغ حالة نهائية.هذا هو الاستدعاء الذي يحرّك الأموال. كل ما تحتاجه من جانبك — سجل الطلب والمبلغ وتفويض عميلك — ينبغي أن يكون محفوظًا بالفعل قبل أن ترسله.متن الطلب
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.استجابات الخطأ
400 — خطأ في التحقق
400 — خطأ في التحقق
المتن لم يطابق المخطط.الأسباب الشائعة:
transactionId ليس من 24 حرفًا سداسيًا عشريًا، أو غياب billId، أو غياب ref، أو ref أطول من 100 حرف.ما العمل: صحّح الطلب. لا تعد إرساله دون تغيير أبدًا.401 — رمز وصول مفقود أو غير صالح
401 — رمز وصول مفقود أو غير صالح
403 — مرجع مكرر
403 — مرجع مكرر
المرجع السبب الأكثر شيوعًا هو إعادة استخدام مرجع
ref مستخدم بالفعل مع هذا الشريك.ref الاكتشاف في الدفع. أرسل قيمة مختلفة، مثلًا pay- قبل معرّف طلبك.ما العمل: قبل إعادة المحاولة، تحقق من الحالة الحالية للمعاملة عبر الحصول على المعاملة بالمعرّف. إذا كانت بالفعل PROCESSING، فقد نفذت دفعتك ولا شيء لإعادة إرساله.404 — غير موجودة أو غير قابلة للدفع
404 — غير موجودة أو غير قابلة للدفع
المعاملة غير موجودة ضمن حسابك، أو أنها ليست في حالة قابلة للدفع، أو أن الحالات الثلاث كلها تُجيب بـ
billId ليس من ضمن فواتيرها.404 — بما في ذلك معاملة تعود إلى شريك آخر، حتى لا تؤكد واجهة API أبدًا وجود معاملة تخص غيرك.ما العمل: أعد قراءة المعاملة. إذا لم تعد status هي READY، فقد بدأت الدفعة بالفعل؛ استعلم عنها دوريًا بدلًا من إرسال دفعة أخرى.409 — الفاتورة مدفوعة مسبقًا
409 — الفاتورة مدفوعة مسبقًا
هذه الفاتورة بعينها سُدِّدت بالفعل.ما العمل: تعامل معها كنتيجة ناجحة تملكها بالفعل. ابحث عن المعاملة المدفوعة في قائمة المعاملات واستخدم إيصالها. لا تحمّل عميلك المبلغ مرتين.
409 — دفعة قيد التنفيذ
409 — دفعة قيد التنفيذ
دفعة أخرى للفاتورة نفسها لم تنتهِ بعد.ما العمل: استعلم دوريًا عن المعاملة الجارية بالفعل. إرسال هذا مجددًا لن يجعلها تنتهي أسرع.
503 — الشريك غير متاح
503 — الشريك غير متاح
تعذّر الوصول إلى مُصدِر الفواتير، أو أنه موقوف حاليًا.ما العمل: لم يُخصم أي مبلغ. لا تزال عملية الاكتشاف بحالة
READY، لذا يمكنك دفع billId نفسه لاحقًا — بالمرجع ref نفسه، فهو لم يُستهلك قط.503 — المصادقة غير متاحة
503 — المصادقة غير متاحة
لم نتمكن من التحقق من مفتاحك في الوقت المحدد. مفتاحك ليس هو المشكلة.ما العمل: انتظر مدة
Retry-After (5 ثوانٍ) وأعد إرسال الطلب نفسه. لم يصل الطلب أبدًا إلى مسار الدفع، لذا فإعادة إرساله آمنة.503 — الخدمة غير متاحة
503 — الخدمة غير متاحة
واجهة Bill Payment API في صيانة مُخطط لها.ما العمل: التزم بـ
Retry-After وأعد المحاولة.500 — خطأ داخلي
500 — خطأ داخلي
حدث خلل من جانبنا.ما العمل: لا تعد إرسال الدفعة. اقرأ المعاملة أولًا — إذا كانت
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 مختلفًا للاكتشاف وآخر للدفع. يكفي وضع disc- وpay- قبل معرّف طلبك.لا تعد الإرسال عند انتهاء المهلة أبدًا
اقرأ المعاملة أولًا. انتهاء مهلة الشبكة لا يعني أن الدفعة لم تحدث.
اخصم انطلاقًا من total
اخصم من عميلك قيمة
total التي أرجعتها واجهة API، لا قيمة حسبتها بنفسك.Endpoints ذات الصلة
اكتشاف الفواتير
اعثر على ما هو قابل للدفع
الحصول على المعاملة بالمعرّف
استعلم دوريًا عن النتيجة
تنزيل الإيصال
إثبات الدفع
الحصول على المعاملة بالمرجع
استعد استجابة ضائعة
دفع الفواتير
الشرح الكامل
الاستعلام الدوري عن الحالة
مُستعلِم دوري بجودة الإنتاج

