Skip to main content
تغطي هذه الصفحة حزمة Flutter الرسمية من Dodo Payments، dodopayments_checkout على pub.dev. توجد أيضًا حزمة منفصلة أنشأها المجتمع. راجع مشاريع المجتمع.

Checkout Sessions API

أنشئ checkout_url الذي يفتحه هذا SDK، من الواجهة الخلفية لديك.

Mobile Integration Guide

تعرّف على كيفية اندماج هذا SDK في تدفق الدفع الكامل عبر الأجهزة المحمولة.
يفتح dodopayments_checkout صفحة الدفع المستضافة من Dodo Payments في SFSafariViewController على iOS وفي Custom Tab على Android، ويُرجع CheckoutResult مكتوب النوع. ويستخدم رمز native نفسه الذي تستخدمه حزم SDK المستقلة لـ iOS و Android، كما أن منطق الدفع بالكامل موجود في ذلك الرمز native. تمرر طبقة Dart كل استدعاء عبر قناة Pigeon مكتوبة النوع. لا تحتوي الحزمة على أي API key ولا تستدعي API الخاصة بـ Dodo Payments مطلقًا. المتطلبات: Flutter 3.44 أو أحدث مع Dart 3.12 أو أحدث، وiOS 16 أو أحدث، وAndroid minSdk 23.

التثبيت

1

Add the Dependency

أضف الحزمة إلى pubspec.yaml:
pubspec.yaml
يتطلب تخصيص المظهر الإصدار 1.1.0 أو أحدث.تُجمّع إضافة Android مقابل Android SDK 35 افتراضيًا. إذا كانت إضافة أخرى تتطلب compileSdk أعلى، فعيّن dodoCompileSdk في gradle.properties الخاص بتطبيقك.
2

Register a Callback URL Scheme

سجّل URL scheme لكي يوجّه نظام التشغيل عنوان URL للعودة الخاص بالدفع إلى تطبيقك. استخدم هذا المخطط في returnUrl الذي تمرره إلى SDK، وعيّن عنوان URL نفسه كقيمة return_url لجلسة الدفع عند إنشاء الجلسة من الواجهة الخلفية لديك. لا يلزم أن يحمّل عنوان URL صفحة حقيقية.
أضف نوع URL للمخطط الخاص بك في ios/Runner/Info.plist:
ios/Runner/Info.plist
لا يستطيع SFSafariViewController اعتراض عنوان URL للعودة الخاص به، لذلك يفتح iOS عنوان URL في تطبيقك بدلًا من ذلك. مرّر كل عنوان URL وارد إلى SDK، مثلًا من app_links:
يمكنك تمرير كل عنوان URL. يعمل handleOpenURL فقط على عنوان URL الذي يطابق returnUrl الخاص بالدفع الجاري، ويحلّ true له. وبالنسبة إلى أي عنوان URL آخر، فإنه يحلّ false. وعلى Android، يحلّ دائمًا false.

الاستخدام

استدعِ DodoCheckout.instance.start باستخدام checkout_url من الواجهة الخلفية لديك:
يستقبل onEvent الأحداث التي تكون فيها type هي CheckoutEventType.opened أو returnReceived أو closed. استخدمها للتسجيل فقط، ولا تستخدمها مطلقًا لتحديد النتيجة.

معنى النتيجة

ينشئ SDK قيمة CheckoutResult من معلمات query في عنوان URL للعودة.
result.status تلميح لواجهة المستخدم، وليس دليلًا على الدفع. أكّد كل عملية دفع من الواجهة الخلفية لديك، باستخدام webhook payment.succeeded أو subscription.active.
CheckoutStatus
مطلوب
إحدى خمس قيم:
  • succeeded: يحتوي عنوان URL للعودة على status=succeeded (دفعة لمرة واحدة) أو status=active (اشتراك).
  • failed: تم رفض الدفع (status=failed).
  • cancelled: أغلق العميل عرض المتصفح قبل وصول عنوان URL للعودة. لا يعرف SDK النتيجة، وقد تكون عملية الدفع قد نجحت، لذا لا تعرض شاشة فشل. سوِّ الجلسة المتروكة بدلًا من ذلك.
  • pending: ستتم تسوية الدفع لاحقًا (status=processing أو أي قيمة requires_*)، أو كانت معلمة status مفقودة أو غير معروفة. سوِّها كما تفعل مع cancelled.
  • expired: انتهت صلاحية جلسة الدفع (status=expired).
String?
معلمة query payment_id، عندما يتضمن عنوان URL للعودة واحدة. اعرضها في واجهة المستخدم لديك، لكن لا تستخدمها لمنح صلاحية الوصول. راجع التحقق من الدفع.
String?
معلمة query subscription_id. تُعيّن لعمليات دفع الاشتراكات.
List<String>?
معلمة query license_key. تُعيّن عندما تتضمن عملية الدفع منتجات مفاتيح ترخيص.
String?
معلمة query email. تُعيّن عندما تلتقط عملية الدفع عنوان بريد إلكتروني.
Map<String, String>
كل معلمات query من عنوان URL للعودة، حرفيًا.

التحقق من الدفع

Webhooks

تستدعي Dodo Payments الواجهة الخلفية لديك عندما تنجح عملية دفع أو يتفعّل اشتراك.

Get Payment Detail

ابحث عن paymentId باستخدام secret key للتحقق من حالته.
امنح صلاحية الوصول فقط بعد أن يؤكد أحد هذه العناصر نجاح الدفع. لا تعتمد على result.status وحده.

تخصيص المظهر

لتغيير شريط أدوات متصفح الدفع والأزرار ونظام الألوان، مرّر BrowserCustomization كـ customization في CheckoutParams. تعرض Android Custom Tabs وiOS SFSafariViewController عناصر تحكم native مختلفة، لذلك تُقسّم الخيارات إلى AndroidBrowserOptions وIosBrowserOptions. تتجاهل كل منصة خيارات المنصة الأخرى. كل حقل اختياري وقيمته الافتراضية null. بالنسبة إلى حقل null، لا يعيّن SDK هذا الخيار وتطبّق المنصة قيمتها الافتراضية الخاصة.
Color?
لون خلفية شريط الأدوات.
Color?
لون شريط التنقل.
Color?
لون الفاصل أعلى شريط التنقل.
CloseButtonStyle?
يعرض standard رمز “X” الخاص بالنظام. ويعرض back سهم رجوع يرسمه SDK.
CloseButtonPosition?
جانب شريط الأدوات الذي يظهر فيه زر الإغلاق: start أو end.
bool?
يعرض رمز المشاركة في شريط الأدوات. يخفيه false.
bool?
يعرض عنوان الصفحة أسفل URL في شريط الأدوات.
bool?
يخفي شريط الأدوات تلقائيًا أثناء تمرير الصفحة.
bool?
يعرض “Bookmark this page” في قائمة الخيارات الإضافية.
bool?
يعرض “Download page” في قائمة الخيارات الإضافية.
BrowserColorScheme?
يفرض light أو dark ذلك المظهر بغض النظر عن إعداد النظام على الجهاز. ويتبع system إعداد النظام.
DismissButtonStyle?
نمط زر الإغلاق: done أو close أو cancel. يحدد iOS ما إذا كان سيعرضه كتسمية أو كرمز.
PresentationStyle?
يعرض pageSheet (المستخدم عند ترك null) بطاقة يمكن للعميل تمريرها إلى الأسفل لإغلاقها. يغطي fullScreen الشاشة بأكملها.
bool?
يتيح طي شريط الأدوات أثناء تمرير الصفحة. ولا يظهر تأثيره إلا عندما تكون قيمة presentationStyle هي fullScreen. ومع pageSheet، تظل الأشرطة مثبتة بصرف النظر عن هذا الإعداد.
BrowserColorScheme?
يفرض light أو dark ذلك المظهر بغض النظر عن إعداد النظام على الجهاز. ويتبع system إعداد النظام.
لا يوفّر iOS خيارًا للون شريط الأدوات، لأن خصائص التلوين الأساسية لـ SFSafariViewController مهملة منذ iOS 26.

الأخطاء

يطرح start الخطأ CheckoutException فقط عند سوء الاستخدام أو حدوث عطل في المنصة. اقرأ السبب من code، وهو CheckoutErrorCode. توجد سلسلة الرمز native في nativeCode. يكون إلغاء العميل أو رفض الدفع نتيجةً دائمًا، وليس استثناءً.
  • invalidCheckoutUrl (INVALID_CHECKOUT_URL): ليست checkoutUrl عنوان URL لجلسة دفع https (مسار يبدأ بـ /session/) على checkout.dodopayments.com أو test.checkout.dodopayments.com.
  • invalidReturnUrl (INVALID_RETURN_URL): ليست returnUrl عنوان URL مطلقًا يحتوي على مخطط ومضيف.
  • alreadyInProgress (ALREADY_IN_PROGRESS): هناك عملية دفع أخرى قيد التشغيل. لا يمكن تشغيل أكثر من عملية دفع واحدة في الوقت نفسه.
  • platformError (PLATFORM_ERROR): عطل غير متوقع في المنصة. تُحوّل أخطاء native غير المعروفة أيضًا إلى هذا الرمز.

الجلسات المتروكة

يسجّل SDK native جلسة الدفع عند بدء الدفع، ويمسح السجل فقط عندما تنتهي عملية الدفع بالقيمة succeeded أو failed أو expired. يظل السجل موجودًا عند إنهاء التطبيق أثناء الدفع، وبعد نتيجة cancelled أو pending. تحقّق من وجوده عند التشغيل التالي وبعد كل نتيجة cancelled أو pending.
abandoned.sessionId هو معرّف جلسة الدفع، ويبدأ بـ cks_. abandoned.createdAt هو وقت بدء عملية الدفع DateTime. يمكن للواجهة الخلفية لديك البحث عن الجلسة باستخدام Get Checkout Session، الذي يعيد payment_id وpayment_status الخاصين بها. إلى أن تصل عملية الدفع إلى حالة نهائية، تعامل معها على أنها معلّقة وليست فاشلة.

ذات صلة

Mobile Integration Guide

العقد نفسه لـ Android وiOS وReact Native.

Community Projects

توجد أيضًا حزمة Flutter منفصلة أنشأها المجتمع.
آخر تعديل في ٢٦ سبتمبر ٢٠٢٦