Skip to main content

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 للدفع. صادِق على هذا الطلب باستخدام رمز الجلسة الخاص بالمستخدم المسجّل دخوله.
الأمان: تتواصل تطبيقات الهاتف المحمول مع خادم 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-iosSFSafariViewController. يتطلب iOS 16 أو إصدارًا أحدث.

React Native

@dodopayments/react-native-checkout، وهو Turbo Module يعمل فوق النواتين الأصليتين. يتطلب React Native 0.76 أو إصدارًا أحدث.

Flutter

dodopayments_checkout، وهي قناة Pigeon تعمل فوق النواتين الأصليتين. تتطلب Flutter 3.44 أو إصدارًا أحدث.
إن status الذي تحصل عليه هو تلميح لواجهة المستخدم، وليس دليلًا على الدفع. أكّد كل عملية دفع من خادم Backend لديك عبر webhook ‏payment.succeeded / subscription.active، أو باسترداد الدفع باستخدام مفتاحك السري.

تسجيل مخطط عنوان URL لإعادة التوجيه

تعيد SDKs الأربعة التحكم إلى تطبيقك عبر مخطط URL مخصّص تختاره أنت، مثل myapp://checkout/return. سجّله مرة واحدة لكل منصة:
android/app/build.gradle
يُعلن manifest الخاص بـ SDK نفسه عن نشاط إعادة التوجيه، لذا لا توجد حاجة لإضافة manifest XML.
هل تفضّل بناؤه بنفسك؟ افتح 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.
آخر تعديل في ٣١ يوليو ٢٠٢٦