شارك المقالة
كود الدفع النقدي Kiosk من Paymob في Flutter وحالة الانتظار

كود الدفع النقدي Kiosk من Paymob في Flutter وحالة الانتظار

اعرض كود Kiosk من Paymob في Flutter مع وقت الصلاحية وحالة الانتظار، وافصل رقم المرجع عن تأكيد الدفع الفعلي من…

كود Kiosk من Paymob في Flutter هو مرجع لعملية دفع نقدي ينتظر استخدامها لاحقًا، وليس إثبات سداد. إنشاء المرجع قد ينجح بينما تظل حالة الطلب pending أو awaiting_payment. لذلك يجب أن تعرض شاشة التعليمات الرقم والمدة والمبلغ من خادمك، وتنتظر تأكيد النتيجة قبل تسليم المنتج.

ما الذي يدعمه Kiosk؟

توثيق Paymob الذي روجع يصف Kiosk في السوق المصري. لا يعني ذلك أن أي ماكينة دفع أو أي علامة تجارية أو أي دولة تقبل المرجع نفسه. تحقق من وسيلة الدفع المفعلة وحساب التاجر وتعليمات الشبكة، ولا تكتب للمستخدم «ادفع من أي ماكينة فوري» دون تأكيد دعم ذلك المسار فعليًا.

المقال يركز على عرض مرجع يعيده خادمك بعد تكامل صحيح، ولا يفترض أن حقل id في أي استجابة هو الرقم الذي يجب أن يقدمه العميل. قد يكون id معرّف معاملة داخليًا؛ استخرج حقل المرجع الموثق من استجابة المسار الذي تستخدمه، ثم حوّله في الخادم إلى عقد واضح باسم referenceCode.

فصل المرجع عن المعرّفات الأخرى

لا تخلط بين Integration ID ورقم الطلب ومعرّف المعاملة وكود السداد. Integration ID يحدد وسيلة الدفع على حساب التاجر، والطلب يربط الشراء في نظامك، أما المرجع فهو ما يُعرض للمستخدم وفق تعليمات الدفع. لا تطلب من العميل إدخال Integration ID في الماكينة ولا ترفع الحالة إلى paid عند الحصول عليه.

{"orderId":"order_demo_1","referenceCode":"00123456","expiresAt":"2027-01-01T00:00:00Z","status":"awaiting_payment"}

هذا JSON عقد توضيحي من خادمك وليس استجابة Paymob حرفيًا. يجب أن يحدد الخادم المبلغ والعملة والتعليمات أيضًا عند بناء الشاشة. احفظ referenceCode نصيًا حتى لا تضيع الأصفار في البداية، ولا تحوّله إلى int لمجرد أنه يبدو أرقامًا. اعرض وقت الانتهاء في المنطقة الزمنية المناسبة للمستخدم مع الاحتفاظ بـUTC في النقل.

التحقق من بنية المرجع وصلاحيته

يتحقق النموذج التالي من تطابق الطلب ووجود المرجع ووقت انتهاء UTC غير منقضٍ. لا ينفذ API أو ينشئ رمزًا حقيقيًا؛ مهمته منع عرض بيانات ناقصة أو مرجع يخص طلبًا آخر. إنشاء المرجع وفحص ملكيته يحدثان في Backend موثق مثل بقية وسائل الدفع.

class KioskReference {
  const KioskReference(this.orderId, this.referenceCode, this.expiresAt);
  final String orderId;
  final String referenceCode;
  final DateTime expiresAt;
  static KioskReference parse(Object? body, String orderId, DateTime now) {
    if (body is! Map<String, dynamic> || body['orderId'] != orderId) {
      throw const FormatException('Mismatched kiosk order');
    }
    final code = body['referenceCode'];
    final rawExpiry = body['expiresAt'];
    final expiry = rawExpiry is String ? DateTime.tryParse(rawExpiry) : null;
    if (code is! String || code.trim().isEmpty || expiry == null ||
        !expiry.isUtc || !expiry.isAfter(now.toUtc())) {
      throw const FormatException('Invalid kiosk reference');
    }
    return KioskReference(orderId, code, expiry);
  }
}

تجربة الاستخدام أثناء الانتظار

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

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

التحقق في الخادم

يُصادق خادمك على callback وفق HMAC الموثق للمسار، ويطابق المعاملة والطلب والمبلغ والعملة والحالة. كود السداد ليس كلمة مرور ولا تفويضًا لعرض تفاصيل طلب أي مستخدم؛ احمِ نقطة الاستعلام بمصادقة وملكية الطلب. لا تسجّل رموز الوصول اللازمة لإنشاء المرجع في التطبيق أو صور الدعم.

حالات الاختبار

اختبر مرجعًا يبدأ بصفر، ومرجعًا فارغًا، وطلبًا غير مطابق، ومدة منتهية، ووقتًا بلا منطقة زمنية، وتأخر التأكيد. اختبر دفعًا يؤكده الخادم بعد مغادرة الشاشة، وإشعارًا مكررًا، وعودة المستخدم إلى الطلب نفسه. البيانات في المثال وهمية؛ لا تصلح للدفع في ماكينة، ولم تُنفذ بها أي عملية نقدية أو إلكترونية.

حفظ المرجع واستعادته

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

لفهم إعداد التكامل الذي يصدر المرجع، ابدأ من شرح Paymob في Postman: إنشاء Intention والتحقق من Callback ثم طبّق حالة الانتظار في واجهة العميل دون اعتبار المرجع إثبات دفع.

مراجع التنفيذ الرسمية

شاهد أيضًا
مقالات ذات صلة
🚫 مانع الإعلانات مفعل

يجب إيقاف مانع الإعلانات لاستكمال تصفح الموقع