Quick Start
ابدأ تشغيل تكامل الدفع عبر الجوال في 4 خطوات بسيطة
Platform Examples
أمثلة تعليمات برمجية كاملة لـ Android وiOS وReact Native وFlutter
توفر Dodo Payments رسميًا SDK للدفع لكل من Android وiOS وReact Native
وFlutter. يغلّف كل منها النمط الموضح أدناه (فتح عنوان URL للدفع، والتقاط
عملية الإرجاع، وتحليل النتيجة) خلف استدعاء
start(...)
واحد مكتوب النوع، مع دعم مدمج لاسترداد الجلسات المتروكة. استخدم WebView يدويًا فقط
إذا لم يكن أي منها مناسبًا لمكدس التقنيات لديك.المتطلبات الأساسية
قبل دمج Dodo Payments في تطبيق الهاتف المحمول، تأكد من توفر ما يلي لديك:- حساب Dodo Payments: حساب تاجر نشط مع إمكانية الوصول إلى API
- بيانات اعتماد API: مفتاح API ومفتاح سر webhook من لوحة التحكم
- مشروع تطبيق الهاتف المحمول: تطبيق Android أو iOS أو React Native أو Flutter
- خادم Backend: لإنشاء جلسات الدفع بأمان
سير عمل التكامل
يتبع تكامل الهاتف المحمول عملية آمنة من 4 خطوات، يتولى فيها خادم Backend استدعاءات API ويدير تطبيق الهاتف المحمول تجربة المستخدم.1
Backend: Create Checkout Session
Checkout Session API Docs
تعرّف على كيفية إنشاء جلسة دفع في خادم Backend باستخدام Node.js وPython وغيرهما. راجع الأمثلة الكاملة ومراجع المعلمات في وثائق Checkout Sessions API المخصصة.
الأمان: يجب إنشاء جلسات الدفع على خادم Backend، وليس في تطبيق الهاتف المحمول مطلقًا. يحمي ذلك مفاتيح API الخاصة بك ويضمن إجراء التحقق المناسب.
2
Mobile: Get Checkout URL
يستدعي تطبيق الهاتف المحمول خادم Backend للحصول على عنوان URL للدفع. صادِق
على هذا الطلب باستخدام رمز الجلسة الخاص بالمستخدم المسجّل دخوله.
- iOS (Swift)
- Android (Kotlin)
- React Native (JavaScript)
- Flutter (Dart)
الأمان: تتواصل تطبيقات الهاتف المحمول مع خادم Backend الخاص بك فقط، ولا تتواصل مطلقًا مباشرةً مع Dodo Payments API.
3
Mobile: Open Checkout in Browser
افتح عنوان URL للدفع في متصفح آمن داخل التطبيق لمعالجة الدفع.
أو تجاوز الإعداد اليدوي بالكامل باستخدام SDK الدفع الرسمي لمنصتك.
Pick your mobile SDK
خطوات التثبيت وإرشادات الإعداد لـ Android وiOS وReact Native وFlutter.
4
Backend: Handle Payment Completion
عالج اكتمال الدفع عبر webhooks وعناوين URL لإعادة التوجيه لتأكيد حالة الدفع.
اختر SDK الخاص بك
يعرِض كل SDK للهاتف المحمول العقد نفسه: إذ يفتح استدعاءstart(...)
واحد صفحة الدفع المستضافة لدى Dodo في واجهة المتصفح الأصلية للمنصة، ويعيد
CheckoutResult مكتوب النوع، تكون قيمة status فيه هي succeeded أو failed أو cancelled أو
pending أو expired. لا يحتفظ أي منها بمفتاح API أو يستدعي Dodo
Payments API، كما تدعم جميعها استرداد الجلسات المتروكة.
Android
يفتح
com.dodopayments.api:checkout-android علامة تبويب Chrome مخصّصة. يتطلب minSdk 23.iOS
يفتح
dodopayments-mobile-sdk-ios SFSafariViewController. يتطلب iOS 16 أو إصدارًا أحدث.React Native
@dodopayments/react-native-checkout، وهو Turbo Module يعمل فوق النواتين الأصليتين. يتطلب React Native 0.76 أو إصدارًا أحدث.Flutter
dodopayments_checkout، وهي قناة Pigeon تعمل فوق النواتين الأصليتين. تتطلب Flutter 3.44 أو إصدارًا أحدث.تسجيل مخطط عنوان URL لإعادة التوجيه
تعيد SDKs الأربعة التحكم إلى تطبيقك عبر مخطط URL مخصّص تختاره أنت، مثلmyapp://checkout/return. سجّله مرة واحدة لكل
منصة:
- Android
- iOS
- Expo
android/app/build.gradle
هل تفضّل بناؤه بنفسك؟ افتح
checkout_url في WebView واعترض
التنقل إلى return_url، ثم اقرأ معلمات الاستعلام status وpayment_id.
تتولى SDKs أعلاه ذلك نيابةً عنك في واجهة المتصفح الفعلية للمنصة، ولهذا يظل
Apple Pay وGoogle Pay يعملان.أفضل الممارسات
- الأمان: لا تُضمّن مفتاح API في تطبيقك مطلقًا. أنشئ جلسات الدفع على خادم Backend، ومرّر فقط
checkout_urlالناتج إلى العميل. - المرجعية: تعامل مع
CheckoutResult.statusعلى أنه تلميح لواجهة المستخدم. امنح الوصول فقط بعد أن يؤكد خادم Backend الدفع. - تجربة المستخدم: اعرض حالة تحميل أثناء إنشاء خادم Backend للجلسة، وتعامل مع
cancelledكنتيجة عادية بدلًا من اعتبارها خطأ. - الاختبار: استخدم وضع الاختبار وبطاقات الاختبار، وتحقق من دورة عنوان URL لإعادة التوجيه على جهاز فعلي وكذلك على محاكي.
استكشاف الأخطاء وإصلاحها
المشكلات الشائعة
- لم تصل معاودة الاتصال مطلقًا: يجب أن يطابق المخطط في
returnUrlالمخطط الذي سجّلته. في Android، يكون ذلك هوdodoCallbackSchemeفي manifest placeholder؛ وفي iOS وReact Native، يكون هوInfo.plistلنوع URL. - تعود عملية الدفع إلى المتصفح بدلًا من تطبيقك (iOS): لم تمرّر عنوان URL الوارد. استدعِ
DodoCheckout.handleOpenURL(url)من.onOpenURLأوscene(_:openURLContexts:)أو مستمعLinkingفي React Native. PLATFORM_ERRORفي Android: غالبًا ما يكون السبب عدم تطابق المخطط. وقد يظهر أيضًا إذا عيّنMainActivityالقيمةandroid:taskAffinity=""(وهي القيمة الافتراضيةflutter create)، ما يسمح لبعض إصدارات OEM بفقدان عملية الدفع الجارية.ALREADY_IN_PROGRESS: لا تزال عملية دفع مفتوحة. انتظر العملية السابقة أو أغلقها قبل بدء عملية أخرى.- فشل البناء بسبب placeholder غير محلول: أضفت Android SDK لكنك لم تعيّن
manifestPlaceholders["dodoCallbackScheme"]. - نجح الدفع لكن لم يُمنح الوصول: هذا متوقع إذا كنت تعتمد على نتيجة الهاتف المحمول. امنح الوصول من webhook
payment.succeeded/subscription.activeبدلًا من ذلك.
موارد إضافية
للاستفسارات أو طلب الدعم، تواصل مع support@dodopayments.com.