البدء السريع

1. اختر البيئة

يمنحك LuxPay عنوان Sandbox وعنوان Production كلٌ على حدة. لا تستبدل النطاق داخل الشيفرة في عدة مواضع؛ استخدم متغيرًا مثل LUXPAY_BASE_URL واضبطه حسب بيئة النشر. ابدأ دائمًا بطلب GET /health وتحقق من أن الخدمة تعيد status: ok.

2. احصل على رمز الوصول

لتطبيقات العملاء استخدم تسجيل العميل أو دخوله. ولأنظمة الأعمال استخدم مسار موظف النشاط أو وسيلة اعتماد خدمية توفرها LuxPay. أرسل الرمز في Authorization: Bearer <token> عبر HTTPS فقط. لا تخزن كلمة المرور بعد تسجيل الدخول.

3. اقرأ المحافظ والرصيد

نفّذ GET /wallets ثم استخدم معرف المحفظة في GET /wallets/{walletId}/balance. الرصيد المتاح ليس مساويًا دائمًا للرصيد المخزن؛ فهو يستبعد المبلغ المحجوز. لا تحسب الرصيد من سجل العمليات على جهاز العميل.

4. نفّذ عملية آمنة

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

5. جهّز التشغيل

طبّق مهلة اتصال، ومحاولات محدودة مع backoff، وربطًا بين X-Request-ID وسجلاتك. تعامل مع 401 و403 و409 و422 و429 كحالات مختلفة، ولا تعرض رسالة الخادم الداخلية مباشرة للمستخدم النهائي.