منع التكرار وإعادة المحاولة

لماذا المفتاح إلزامي؟

الانقطاع قد يحدث بعد أن يستقبل LuxPay الطلب وقبل أن يستقبل عميلك الاستجابة. إعادة الطلب دون هوية ثابتة قد تنشئ عملية مالية ثانية. مفتاح منع التكرار يعرّف النية التجارية نفسها عبر محاولات النقل.

موضع المفتاح

مسارات المحفظة القديمة في العقد الحالي تستقبل idempotency_key داخل JSON، ومنها الإيداع والسحب والتحويل والصرف والتسوية. مسارات الدفع المنسقة تستخدم ترويسة Idempotency-Key. يوضح كل Endpoint موضع المفتاح في حقل Idempotency داخل المرجع.

توليد المفتاح

استخدم UUID أو معرفًا عالي العشوائية، واربطه بسجل الطلب في نظامك قبل إرسال الشبكة. لا تستخدم الوقت وحده ولا رقم المستخدم وحده. المفتاح نفسه يجب أن يحمل الجسم المنطقي نفسه؛ تغيير المبلغ أو المحفظة مع إعادة استخدام المفتاح يعد تعارضًا ويجب أن يعالج كخطأ 409.

سياسة إعادة المحاولة

أعد المحاولة عند انقطاع الشبكة و5xx المحددة وبمهلة متزايدة، مع المفتاح نفسه. لا تعد المحاولة تلقائيًا عند 401 أو 403 أو 422. عند 429 احترم Retry-After إن وجد. إذا عادت استجابة Duplicate ناجحة، تعامل معها بوصفها نتيجة العملية الأصلية واحفظ معرفها.

التخزين والمصالحة

احتفظ بالمفتاح، Hash الحمولة، معرف LuxPay، الحالة، وأوقات المحاولات. هذه البيانات تسمح بمطابقة ما حدث في نظامك مع دفتر LuxPay دون الاعتماد على الذاكرة أو السجلات النصية فقط.