صفحة دفع Paymob في Flutter يجب أن تفتح تجربة Checkout الموثقة ثم تعرض حالة الطلب التي يؤكدها الخادم. المقال القديم كان يعرض WebView ويطبع الرابط النهائي الذي يتضمن رمز الجلسة؛ هذا يخلط بين عرض الصفحة وإتمام الدفع، وقد يكشف بيانات الجلسة في السجلات. سنستخدم صفحة متابعة بسيطة مع متصفح خارجي ومسار واضح لإعادة التحقق.
قبل بناء الصفحة
ابدأ بعقد BackendCheckoutApi في درس ربط Paymob، وثبت dio 5.11.1 وurl_launcher 6.3.3. يحتاج التطبيق خادمًا فعليًا يُنشئ الجلسة وفق الطلب ويعيد رابطًا صالحًا قصير العمر. المكوّن لا يجمع رقم البطاقة أو CVV داخل TextField، ولا يحتاج إلى مفتاح التاجر السري لعرض Checkout.
اختيار متصفح خارجي في هذا المثال مقصود لتفادي افتراض أن كل وسيلة دفع تدعم WebView بنفس الشكل. إذا اخترت تجربة مدمجة يدعمها المزوّد، فاتبع إعدادها الحالي واختبر التحويل إلى تطبيقات البنوك و3D Secure وApple Pay حيث تكون متاحة. لا تمنع كل تنقل خارجي ثم تستنتج أن خدمة الدفع معطلة.
مصدر حالة الشاشة
يحمل CheckoutController حالة بدء العملية والتحقق والخطأ. الدالة openCheckout تحقن من الخارج لتسهيل الاختبار؛ اكتمالها لا يضع الطلب في paid. الطريقة الوحيدة هنا لعرض التأكيد هي استجابة status من خادمك الموثق، بعدما يتحقق من نتيجة المزوّد.
import 'package:flutter/foundation.dart';
import 'checkout.dart';
class CheckoutController extends ChangeNotifier {
CheckoutController(this.api, this.openCheckout, this.orderId);
final CheckoutApi api;
final Future<void> Function(Uri) openCheckout;
final String orderId;
bool busy = false;
bool _closed = false;
int _generation = 0;
OrderPaymentStatus? status;
String? error;
Future<void> start() async {
if (busy || _closed || status == OrderPaymentStatus.paid) return;
busy = true; error = null; notifyListeners();
try {
final session = await api.create(orderId);
if (_closed) return;
await openCheckout(session.url);
if (!_closed) await refresh();
} catch (_) {
if (!_closed) error = 'تعذر فتح الدفع؛ تحقق من حالة الطلب قبل المحاولة مجددًا';
} finally {
if (!_closed) { busy = false; notifyListeners(); }
}
}
Future<void> refresh() async {
if (_closed) return;
final generation = ++_generation;
try {
final result = await api.status(orderId);
if (!_closed && generation == _generation) { status = result; error = null; }
} catch (_) {
if (!_closed && generation == _generation) error = 'تعذر التحقق من الدفع الآن';
}
if (!_closed && generation == _generation) notifyListeners();
}
@override
void dispose() { _closed = true; _generation++; super.dispose(); }
}
صفحة متابعة الدفع
احفظ CheckoutPage في ملفه، ومرر لها API ومعرّف الطلب. تعرض زرًا لفتح الدفع وزر تحقق مستقلًا، وتعيد الفحص عند عودة التطبيق إلى foreground. تأكد أن baseUrl الخاص بعميلك يستخدم HTTPS وأن allowedHosts يطابق نطاقات Checkout التي يقررها الخادم. لا تمرر رابطًا يكتبه المستخدم مباشرة إلى متصفح الدفع.
import 'package:flutter/material.dart';
import 'package:url_launcher/url_launcher.dart';
import 'checkout.dart';
import 'checkout_controller.dart';
class CheckoutPage extends StatefulWidget {
const CheckoutPage({super.key, required this.api, required this.orderId});
final CheckoutApi api;
final String orderId;
@override
State<CheckoutPage> createState() => _CheckoutPageState();
}
class _CheckoutPageState extends State<CheckoutPage> with WidgetsBindingObserver {
late final CheckoutController controller;
@override
void initState() {
super.initState();
WidgetsBinding.instance.addObserver(this);
controller = CheckoutController(widget.api, (uri) async {
final opened = await launchUrl(uri, mode: LaunchMode.externalApplication);
if (!opened) throw StateError('Browser did not open');
}, widget.orderId);
}
@override
void didChangeAppLifecycleState(AppLifecycleState state) {
if (state == AppLifecycleState.resumed) controller.refresh();
}
@override
void dispose() {
WidgetsBinding.instance.removeObserver(this);
controller.dispose(); super.dispose();
}
@override
Widget build(BuildContext context) => Scaffold(
appBar: AppBar(title: const Text('متابعة الدفع')),
body: ListenableBuilder(listenable: controller, builder: (context, _) => Column(
children: [
Text(controller.status == OrderPaymentStatus.paid
? 'أكد الخادم الدفع' : 'لم يُؤكد الدفع بعد'),
if (controller.error != null) Text(controller.error!),
ElevatedButton(onPressed: controller.busy || controller.status == OrderPaymentStatus.paid
? null : controller.start, child: const Text('فتح صفحة الدفع')),
TextButton(onPressed: controller.refresh, child: const Text('التحقق من الحالة')),
],
)),
);
}
لماذا لا يكفي الرجوع من المتصفح؟
launchUrl في الوضع الخارجي يؤكد فتح التطبيق المناسب، ولا ينتظر بالضرورة انتهاء شراء العميل. لذلك قد يرجع فحص الحالة المباشر awaiting_payment، ثم تصبح paid لاحقًا بعد callback. هذه حالة طبيعية، ويجب ألا تستبدلها برسالة «فشل الدفع» أو تنشئ طلبًا جديدًا دون حاجة.
العودة إلى التطبيق قد تحدث بسبب إلغاء العميل أو إغلاق المتصفح أو اكتمال مصادقة بنكية أو مجرد تنقل. لا تقرأ success=true من deep link وتفتح المحتوى المدفوع. اربط مسار العودة بطلب المستخدم الحالي، وتجاهل أي معرّف لا يملكه الحساب وفق تحقق الخادم، ثم اجلب الحالة من المصدر الموثوق.
حماية دورة الحياة
يتخلص المثال من المراقب والمتحكم عند إغلاق الشاشة، ويتجاهل نتائج التحقق الأقدم إذا وصلت خارج الترتيب. هذا يمنع ردًا متأخرًا من استبدال حالة أحدث أو تحديث واجهة مغلقة. عند توسيع الكود إلى عدة طلبات لا تغيّر orderId تحت نفس المتحكم دون إعادة تهيئة واضحة.
لا تطبع checkoutUrl أو client_secret أو بيانات البطاقة، حتى في مثال تعليمي ينقله مطور إلى تطبيق منشور. سجّل معرّف طلب داخليًا منقحًا عند الحاجة، واعرض رسالة يمكن للمستخدم التصرف بناءً عليها، مثل إعادة التحقق من الحالة، بدل عرض الاستثناء الخام الذي قد يحتوي تفاصيل حساسة.
اختبار الصفحة قبل اعتمادها
اختبر بقاء الطلب قيد الانتظار بعد فتح المتصفح، وعودته مدفوعًا من الخادم، وفشل فتح الرابط، وإغلاق الشاشة أثناء الطلب، وعودة استجابتين بترتيب معكوس. افصل اختبار منطق Dart عن اختبار الدفع الأصلي على الجهاز. لم تُنفذ أي عملية مالية في اختبارات هذا المثال، ولا يمثّل نجاحها اختبارًا لتفعيل حساب التاجر أو تحويل البنك الفعلي.
تعتمد الصفحة على عقد الخادم والنموذج الموضحين في ربط Paymob مع Flutter باستخدام Backend وجلسة Checkout؛ احفظ الملفات بأسمائها ثم اربطها بخادمك بدل نسخ مفتاح التاجر إلى الشاشة.





