شارك المقالة
ربط Paymob مع Flutter باستخدام Backend وجلسة Checkout

ربط Paymob مع Flutter باستخدام Backend وجلسة Checkout

تعلّم ربط Paymob مع Flutter عبر Backend يحسب المبلغ وينشئ جلسة Checkout، مع حماية المفاتيح ومنع الخلط بين إنشاء الجلسة…

ربط Paymob مع Flutter يبدأ بتوزيع المسؤوليات: التطبيق يعرض الطلب ويفتح تجربة الدفع، والخادم يحتفظ بمفاتيح التاجر ويحدد المبلغ ويتحقق من النتيجة. لا تضع API Key أو Secret Key في constants.dart ثم تتوقع أن إخفاء الملف أو تشفير السلسلة يحميهما؛ يمكن استخراج أسرار العميل من التطبيق.

تدفق الدفع الصحيح من البداية

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

ظهرت في المثال القديم خطوات auth/tokens ثم ecommerce/orders ثم payment_keys داخل Flutter. هذه خطوات مسار قديم، ولا يصح مزجها عشوائيًا مع Secret Key وIntention في التكامل الأحدث. راجع منطقة الحساب ونسخة التوثيق، واجعل الاختلاف داخل adapter في الخادم بدل نشر مفاتيح كل مزوّد في الهاتف.

عقد واضح بين التطبيق وخادمك

المثال التالي يخص API تملكه أنت، وليس مسارات Paymob الرسمية. POST على /orders/{id}/checkout ينشئ أو يعيد جلسة نشطة للطلب، وGET على /orders/{id}/payment-status يعيد حالته بعد تحقق الخادم. يجب أن يتحقق الخادم من هوية المستخدم وملكيته للطلب؛ معرّف orderId ليس تصريح وصول بمفرده.

{"orderId":"order_demo_1","checkoutUrl":"https://checkout.example.invalid/session/demo","expiresAt":"2027-01-01T00:00:00Z"}

النطاق في JSON توضيحي ولن ينفذ دفعًا. استخدم نطاق Checkout الموثق لحسابك، وضعه في قائمة السماح. لا تثق بلاحقة نصية عامة مثل contains("paymob")، لأن اسم نطاق مهاجم قد يتضمنها. ينبغي أن تصل المصادقة الخاصة بخادمك عبر العميل الموثق، وألا تُنسخ مفاتيح التاجر إلى رأس يرسله تطبيق الهاتف مباشرة للمزوّد.

مكوّن اتصال قابل للاختبار

يتحقق BackendCheckoutApi من مطابقة معرّف الطلب وبنية الاستجابة وصلاحية الرابط. الدوال لا تستقبل المبلغ من واجهة المستخدم لتقريره، ولا تتجاهل HTTP غير الناجح باستخدام validateStatus يعيد true لكل شيء. اسمح بمرور الخطأ إلى طبقة حالة واضحة بدل إعادة null ثم استخدام value! الذي يسبب انهيارًا لاحقًا.

import 'package:dio/dio.dart';

enum OrderPaymentStatus { awaitingPayment, paid, failed, expired }

OrderPaymentStatus parsePaymentStatus(Object? value) => switch (value) {
  'awaiting_payment' => OrderPaymentStatus.awaitingPayment,
  'paid' => OrderPaymentStatus.paid,
  'failed' => OrderPaymentStatus.failed,
  'expired' => OrderPaymentStatus.expired,
  _ => throw const FormatException('Unknown payment status'),
};

Uri checkedCheckoutUrl(String value, Set<String> allowedHosts) {
  final uri = Uri.tryParse(value);
  if (uri == null || uri.scheme != 'https' || uri.userInfo.isNotEmpty ||
      uri.port != 443 || !allowedHosts.contains(uri.host)) {
    throw const FormatException('Untrusted checkout URL');
  }
  return uri;
}

class CheckoutSession {
  const CheckoutSession(this.orderId, this.url, this.expiresAt);
  final String orderId;
  final Uri url;
  final DateTime expiresAt;
  static CheckoutSession parse(Object? body, String expectedOrderId,
      Set<String> allowedHosts, DateTime now) {
    if (body is! Map<String, dynamic> || body['orderId'] != expectedOrderId ||
        body['checkoutUrl'] is! String || body['expiresAt'] is! String) {
      throw const FormatException('Invalid checkout session');
    }
    final expires = DateTime.tryParse(body['expiresAt'] as String);
    if (expires == null || !expires.isUtc || !expires.isAfter(now.toUtc())) {
      throw const FormatException('Expired or ambiguous session');
    }
    return CheckoutSession(expectedOrderId,
        checkedCheckoutUrl(body['checkoutUrl'] as String, allowedHosts), expires);
  }
}

abstract interface class CheckoutApi {
  Future<CheckoutSession> create(String orderId);
  Future<OrderPaymentStatus> status(String orderId);
}

class BackendCheckoutApi implements CheckoutApi {
  BackendCheckoutApi(this.dio, this.allowedHosts);
  final Dio dio; // Authenticated client for your own HTTPS backend.
  final Set<String> allowedHosts;
  String path(String id) => '/orders/${Uri.encodeComponent(id)}';
  @override
  Future<CheckoutSession> create(String orderId) async {
    final response = await dio.post<Object?>('${path(orderId)}/checkout');
    return CheckoutSession.parse(response.data, orderId, allowedHosts, DateTime.now());
  }
  @override
  Future<OrderPaymentStatus> status(String orderId) async {
    final response = await dio.get<Object?>('${path(orderId)}/payment-status');
    final body = response.data;
    if (body is! Map<String, dynamic> || body['orderId'] != orderId) {
      throw const FormatException('Mismatched order');
    }
    return parsePaymentStatus(body['status']);
  }
}

منع إنشاء عمليات متكررة

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

المبلغ والعملة وبيئة التشغيل

اجعل الخادم مصدر السعر والخصم والشحن والعملة، وافحص اتفاق المبلغ عند استلام النتيجة. لا تستخدم price * 100 كقاعدة عالمية لكل عملة أو مزوّد؛ عرّف وحدات المبلغ حسب عقد الخدمة والعملة. بيانات الاختبار وIntegration IDs الخاصة بها يجب أن تتطابق مع البيئة والمنطقة؛ النقل إلى Live ليس مجرد تغيير متغير في الشاشة.

متابعة النتيجة ومعالجة الفشل

عند العودة من Checkout اطلب حالة الطلب من خادمك. ظهور صفحة نجاح أو وجود success في رابط لا يخول التطبيق تسليم المنتج. قد يتأخر callback أو يغلق المستخدم الصفحة؛ اعرض حالة انتظار مع إجراء تحقق، واحتفظ بمعرّف الطلب ليستعيد المستخدم المحاولة دون إعادة بناء كل العملية.

اختبر JSON ناقصًا، وطلبًا يخص حسابًا آخر، ورابطًا غير موثوق، وجلسة منتهية، وHTTP مرفوضًا، ونقرتين متتاليتين. اختبارات المقال تستخدم مصادر وهمية ولا تتصل بحساب Paymob. تشغيل التكامل الحقيقي يحتاج إعداد الخادم ووسائل الدفع المفعلة واختبارات Sandbox الرسمية.

لضبط بيئة الاختبار قبل بناء العميل، راجع شرح Paymob في Postman: إنشاء Intention والتحقق من Callback ثم انتقل إلى درس صفحة الدفع لعرض الجلسة ومتابعة حالتها.

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

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

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