دورة حياة الدفع

اكتشاف الخدمة

ابدأ بـGET /payment-services لمعرفة المزودين والعملات والطرق المتاحة. لا تثبت اسم مزود داخل التطبيق دون المرور بكتالوج الخدمة. يمكن استخدام مسار select للحصول على next_action المطلوب، مثل إدخال إضافي أو إعادة توجيه أو انتظار تأكيد.

بدء الدفع

POST /payments/initiate يحتاج المبلغ والعملة وطريقة الدفع والقناة، ويستخدم Idempotency-Key في الترويسة. لا ترسل business_id؛ يأتي من سياق المصادقة. الاستجابة 201 لعملية جديدة وقد تكون 200 لإعادة طلب مكرر تم التعرف عليه.

التأكيد والحالة

بعض التدفقات تحتاج confirm مع metadata، وبعضها ينتقل عبر Webhook. استخدم GET /payments/{uuid}/status عندما تحتاج استعلامًا، لكن لا تنشئ Polling سريعًا؛ طبق backoff وحدًا زمنيًا. الحالة النهائية يجب أن تأتي من LuxPay لا من نتيجة واجهة المزود وحدها.

الإلغاء والاسترداد

الإلغاء مسموح فقط في حالات معينة. الاسترداد قد يكون كاملًا عندما لا ترسل amount أو جزئيًا عند إرسال قيمة. استخدم مفتاح منع تكرار مستقلًا لكل نية استرداد، وسجل السبب داخليًا. لا تعالج الاسترداد كتعديل على العملية الأصلية؛ هو حركة مالية مرتبطة بها.

المصالحة

اربط معرف الطلب المحلي بمعرف payment وprovider_ref وRequest ID. عند اختلاف واجهة المستخدم وWebhook واستعلام الحالة، لا تتخذ قرارًا ماليًا من آخر رسالة وصلت فقط؛ طبق قواعد الحالة والمصالحة.