شارك المقالة
Stripe في Flutter باستخدام PaymentSheet وإنشاء PaymentIntent في الخادم

Stripe في Flutter باستخدام PaymentSheet وإنشاء PaymentIntent في الخادم

استخدم Stripe في Flutter باستخدام PaymentSheet، وأنشئ PaymentIntent في الخادم دون كشف Secret Key، مع التحقق من Webhook ومعالجة الإلغاء.

استخدام Stripe في Flutter باستخدام PaymentSheet يفصل جمع بيانات الدفع عن إنشاء العملية وتأكيد الطلب في نظامك. المفتاح Publishable Key مخصص للعميل، بينما Secret Key يبقى في الخادم. لذلك استُبدل المثال القديم الذي ينشئ PaymentIntent مباشرة من Flutter باستخدام SEC_KEY ويعتبر إغلاق واجهة الدفع نجاحًا تجاريًا نهائيًا.

الإعداد المناسب للإصدار

المثال يستهدف واجهة flutter_stripe 14.2.0 التي جرت مراجعتها، ويستخدم PaymentSheet لتطبيق الهاتف. راجع متطلبات Android وiOS في الحزمة، ومنها FlutterFragmentActivity ومتطلبات Theme على Android بحسب الإصدار. لا تفترض أن المثال نفسه يعمل على الويب بالواجهة ذاتها؛ دعم المنصات ووسائل الدفع يحتاج مراجعة خاصة.

اضبط Stripe.publishableKey بالقيمة العامة الصحيحة لبيئة الاختبار ثم طبّق الإعدادات قبل عرض الواجهة. لا تضع sk_test أو sk_live في dart-define أو ملف assets باعتبار أن ذلك يخفيه؛ كل ما يُوزع داخل التطبيق قابل للاستخراج. client_secret خاص بعملية محددة ويجب ألا يُطبع أو يُشارك دون حاجة، لكنه ليس Secret Key الخاص بحساب التاجر.

الخادم ينشئ PaymentIntent

يُرسل التطبيق معرّف الطلب إلى خادم موثق، ثم يقرأ الخادم السعر والعملة من بياناته. لا تقبل totalPrice من واجهة الهاتف على أنه القيمة النهائية، ولا تستخدم double مع round ثم تضربه في 100 لكل العملات. احتفظ بوحدات المبلغ الصغرى الصحيحة وعالج دقة كل عملة وفق مرجع Stripe.

المثال التالي جزء Backend بلغة JavaScript مع اعتمادات محقونة للتوضيح والاختبار. orders يمثل مستودعًا يتحقق من ملكية الطلب، وstripe عميل SDK رسمي مُهيأ في الخادم فقط. activeAttemptId يحدده الخادم ويثبته لمحاولة واحدة، ولا يغيّره الهاتف مع كل إعادة محاولة. بقية البنية مثل المصادقة وقاعدة البيانات ومعالجة Webhook يجب تنفيذها في نظامك.

export async function createStripeSession({ orders, stripe, userId, orderId }) {
  const order = await orders.getOwnedOrder(orderId, userId);
  if (!order || order.status === 'paid') throw new Error('Order unavailable');
  if (!Number.isSafeInteger(order.amountMinor) || order.amountMinor <= 0 ||
      typeof order.currency !== 'string' || !order.activeAttemptId) {
    throw new Error('Invalid server order');
  }
  const intent = await stripe.paymentIntents.create({
    amount: order.amountMinor,
    currency: order.currency,
    metadata: { order_id: order.id },
  }, { idempotencyKey: `order:${order.id}:${order.activeAttemptId}` });
  await orders.attachIntent(order.id, intent.id);
  return { orderId: order.id, clientSecret: intent.client_secret };
}

// Provider-specific signature verification must precede this normalized event.
export async function applyVerifiedPayment({ verifyEvent, request, orders }) {
  const event = await verifyEvent(request);
  if (event.kind !== 'paid') return { updated: false };
  const order = await orders.findByProviderPaymentId(event.paymentId);
  if (!order || event.amountMinor !== order.amountMinor ||
      event.currency !== order.currency || event.orderId !== order.id) {
    throw new Error('Payment/order mismatch');
  }
  // This repository operation must be atomic and idempotent in a real database.
  return orders.commitPaymentOnce({ orderId: order.id, eventId: event.id });
}

دالة applyVerifiedPayment تستقبل حدثًا موحدًا بعد تحقق خاص بالمزوّد؛ event.kind ليس حقلًا تنقله من JSON الخاص بـStripe حرفيًا. نفذ verifyEvent عبر مكتبة Stripe والتحقق من التوقيع والجسم الخام، ثم طابق المعاملة والمبلغ والعملة والطلب. commitPaymentOnce عقد لعملية قاعدة بيانات ذرية تمنع التكرار، وليس مجرد Set في ذاكرة خادم الإنتاج.

عرض PaymentSheet في Flutter

يعيد خادمك clientSecret للعملية المسموح بها، ثم تهيئ الواجهة وتعرضها. المقطع التالي يعتمد enum الحالة من checkout.dart في المكوّن المشترك، ولا يحتوي مفاتيح تاجر ولا ينفذ طلب إنشاء عملية إلى api.stripe.com من الجهاز.

import 'package:flutter_stripe/flutter_stripe.dart';
import 'checkout.dart';

Future<OrderPaymentStatus> showStripePayment({
  required Future<String> Function() createClientSecretOnBackend,
  required Future<OrderPaymentStatus> Function() refreshOrderFromBackend,
}) async {
  final clientSecret = await createClientSecretOnBackend();
  if (clientSecret.isEmpty) throw const FormatException('Missing client secret');
  await Stripe.instance.initPaymentSheet(
    paymentSheetParameters: SetupPaymentSheetParameters(
      paymentIntentClientSecret: clientSecret,
      merchantDisplayName: 'Your store',
    ),
  );
  await Stripe.instance.presentPaymentSheet();
  // Finishing the sheet does not fulfill the order on its own.
  return refreshOrderFromBackend();
}

لا تجعل اكتمال الواجهة قرار التسليم

بعد انتهاء PaymentSheet اطلب حالة الطلب من Backend. قد تحتاج وسيلة الدفع إلى وقت معالجة، أو يصل Webhook بعد استجابة الشاشة. أبقِ الواجهة في حالة انتظار عندما لا يؤكد الخادم الدفع، ولا تمنح المحتوى بناءً على returnUrl أو حدث محلي يستطيع العميل تغييره.

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

سياسة الإعادة وWebhook

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

ماذا اختُبر وما الذي يبقى عليك؟

اختُبرت استدعاءات الواجهات ومنطق العقد بمصادر وهمية، ومنها رفض مبلغ لا يطابق الطلب وعدم اعتماد paid قبل تأكيد الخادم. لم تُنشأ PaymentIntent حقيقية ولم تُجرَ عملية خصم. قبل التشغيل الفعلي اختبر Sandbox والإلغاء والمصادقة الإضافية والتأخر وإعادة المحاولة، وراجع متطلبات المنتج والمنصة ووسائل الدفع المتاحة لحسابك دون افتراض أنها متاحة عالميًا.

لرؤية نمط فتح Checkout والتحقق من الطلب عند العودة في تطبيق Flutter، راجع صفحة دفع Paymob في Flutter وقراءة نتيجة الطلب من الخادم؛ تختلف تهيئة Stripe الأصلية عن الرابط المستضاف، بينما يبقى تأكيد الطلب مسؤولية الخادم.

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

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

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