تغطي هذه الصفحة حزمة 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
أضف الحزمة إلى يتطلب تخصيص المظهر الإصدار 1.1.0 أو أحدث.تُجمّع إضافة Android مقابل Android SDK 35 افتراضيًا. إذا كانت إضافة أخرى تتطلب
pubspec.yaml:pubspec.yaml
compileSdk أعلى، فعيّن dodoCompileSdk في gradle.properties الخاص بتطبيقك.2
Register a Callback URL Scheme
سجّل URL scheme لكي يوجّه نظام التشغيل عنوان URL للعودة الخاص بالدفع إلى تطبيقك. استخدم هذا المخطط في
returnUrl الذي تمرره إلى SDK، وعيّن عنوان URL نفسه كقيمة return_url لجلسة الدفع عند إنشاء الجلسة من الواجهة الخلفية لديك. لا يلزم أن يحمّل عنوان URL صفحة حقيقية.- iOS
- Android
أضف نوع 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 للعودة.
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 هذا الخيار وتطبّق المنصة قيمتها الافتراضية الخاصة.
Android — Custom Tab
Android — Custom Tab
Color?
لون خلفية شريط الأدوات.
لون شريط التنقل.
لون الفاصل أعلى شريط التنقل.
CloseButtonStyle?
يعرض
standard رمز “X” الخاص بالنظام. ويعرض back سهم رجوع يرسمه SDK.CloseButtonPosition?
جانب شريط الأدوات الذي يظهر فيه زر الإغلاق:
start أو end.يعرض رمز المشاركة في شريط الأدوات. يخفيه
false.bool?
يعرض عنوان الصفحة أسفل URL في شريط الأدوات.
bool?
يخفي شريط الأدوات تلقائيًا أثناء تمرير الصفحة.
bool?
يعرض “Bookmark this page” في قائمة الخيارات الإضافية.
bool?
يعرض “Download page” في قائمة الخيارات الإضافية.
BrowserColorScheme?
يفرض
light أو dark ذلك المظهر بغض النظر عن إعداد النظام على الجهاز. ويتبع system إعداد النظام.iOS — SFSafariViewController
iOS — SFSafariViewController
DismissButtonStyle?
نمط زر الإغلاق:
done أو close أو cancel. يحدد iOS ما إذا كان سيعرضه كتسمية أو كرمز.PresentationStyle?
يعرض
pageSheet (المستخدم عند ترك null) بطاقة يمكن للعميل تمريرها إلى الأسفل لإغلاقها. يغطي fullScreen الشاشة بأكملها.bool?
يتيح طي شريط الأدوات أثناء تمرير الصفحة. ولا يظهر تأثيره إلا عندما تكون قيمة
presentationStyle هي fullScreen. ومع pageSheet، تظل الأشرطة مثبتة بصرف النظر عن هذا الإعداد.BrowserColorScheme?
يفرض
light أو dark ذلك المظهر بغض النظر عن إعداد النظام على الجهاز. ويتبع system إعداد النظام.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 منفصلة أنشأها المجتمع.