Skip to main content
تغطي هذه الصفحة حزمة SDK الرسمية للدفع في React Native من Dodo Payments، @dodopayments/react-native-checkout. وهي تفتح صفحة الدفع المستضافة من Dodo Payments في نافذة متصفح أصلية وتعيد نتيجة مكتوبة النوع. توجد حزمة أقدم، dodopayments-react-native-sdk (غير محددة النطاق)، بواجهة API مختلفة. توثق هذه الصفحة الحزمة المحددة النطاق فقط.

Checkout Sessions API

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

Mobile Integration Guide

تعرّف على كيفية اندماج حزمة SDK هذه في مسار الدفع الكامل على الأجهزة المحمولة.
حزمة SDK الخاصة بـ React Native هي Turbo Module يغلّف حزم SDK الأصلية للدفع في iOS وAndroid. تفتح SFSafariViewController على iOS وCustom Tab على Android. ولا تحتوي على مفتاح API ولا على منطق دفع خاص بها، ولذلك لا تستدعي واجهة Dodo Payments البرمجية مطلقًا. يجري الدفع في نافذة المتصفح. تعرض حزمة SDK هذه النافذة وتغلقها، وتقرأ النتيجة من عنوان URL للعودة.
تدعم حزمة SDK هذه البنية الجديدة فقط. وتتطلب React Native 0.77 أو إصدارًا أحدث، وiOS 16 أو إصدارًا أحدث، وAndroid minSdk 24. يجب أن يُبنى تطبيق Android باستخدام compileSdk 34 أو إصدار أحدث.

التثبيت

1

Install the Package

تُربط الحزمة تلقائيًا وتسحب com.dodopayments.api:checkout-android من Maven Central.
يُحلّ الاعتماد الأصلي تلقائيًا، لذا لا حاجة إلى خطوات تثبيت أخرى.
يتطلب تخصيص المظهر الإصدار 1.2.0 أو إصدارًا أحدث.
2

Register a Callback URL Scheme

سجّل مخطط URL لكي يوجّه نظام التشغيل عنوان URL للعودة الخاص بالدفع إلى تطبيقك.
اضبط المخطط كعنصر نائب في البيان داخل android/app/build.gradle:
android/app/build.gradle
استبدل "myapp" بالمخطط الخاص بتطبيقك.
في كل نظام أساسي، عيّن عنوان URL نفسه الذي تستخدمه جلسة الدفع في return_url عند إنشاء خادمك الخلفي للجلسة. تطابق حزمة SDK عنوان URL للعودة وفق المخطط والمضيف والمسار. لا يلزم أن يحمّل عنوان URL صفحة حقيقية.

الاستخدام

استدعِ DodoCheckout.start باستخدام checkout_url من خادمك الخلفي:
يتلقى onEvent أحداثًا تحتوي على type بقيمة checkout.opened أو checkout.return_received أو checkout.closed. استخدمها للتسجيل فقط، وليس لاتخاذ قرار بشأن النتيجة.

إعادة توجيه عنوان URL للعودة

يحتاج iOS إلى مستمع Linking للتعامل مع عنوان URL للعودة، لأن SFSafariViewController لا يستطيع اعتراض عنوان URL للعودة الخاص به. على Android، لا يفعل handleOpenURL شيئًا ويحلّ false، لأن حزمة SDK الخاصة بـ Android تعترض إعادة التوجيه أصليًا. يمكنك تسجيل المستمع على كلا النظامين الأساسيين.
على iOS، يحلّ handleOpenURL إلى true عندما ينتمي عنوان URL إلى عملية الدفع الجارية، وإلى false لأي عنوان URL آخر.

معنى النتيجة

تنشئ حزمة SDK النتيجة من معلمات query في عنوان URL للعودة.
result.status هو تلميح لواجهة المستخدم، وليس إثباتًا للدفع. أكّد كل عملية دفع من خادمك الخلفي، باستخدام payment.succeeded أو webhook 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. تُعيّن لعمليات دفع الاشتراكات.
string[]
معلمة query license_key. تُعيّن عندما يتضمن الدفع منتجات بمفاتيح ترخيص.
string
معلمة query email. تُعيّن عندما يلتقط الدفع عنوان بريد إلكتروني.
Record<string, string>
كل معلمات query من عنوان URL للعودة، كما هي.

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

Webhooks

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

Get Payment Detail

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

تخصيص المظهر

لتغيير شريط أدوات متصفح الدفع والأزرار ونظام الألوان، مرّر customization إلى start(...). تعرض Custom Tabs على Android وSFSafariViewController على iOS عناصر تحكم أصلية مختلفة، لذا تُجمّع الخيارات في كائن android وكائن ios. يقرأ كل نظام أساسي كائنه الخاص فقط. جميع الحقول اختيارية. عند حذف حقل، يطبّق النظام الأساسي الإعداد الافتراضي الخاص به.
string
لون خلفية شريط الأدوات، كسلسلة سداسية عشرية: "#RRGGBB" أو "#AARRGGBB".
string
لون شريط التنقل، كسلسلة سداسية عشرية.
string
لون الفاصل أعلى شريط التنقل، كسلسلة سداسية عشرية.
'default' | 'back'
يعرض default رمز “X” الخاص بالنظام. ويعرض back سهم رجوع ترسمه حزمة SDK.
'start' | 'end'
الجانب من شريط الأدوات الذي يظهر فيه زر الإغلاق.
boolean
يعرض رمز المشاركة في شريط الأدوات. ويخفيه false.
boolean
يعرض عنوان الصفحة أسفل عنوان URL في شريط الأدوات.
boolean
يخفي شريط الأدوات تلقائيًا أثناء تمرير الصفحة.
boolean
يعرض “إضافة الصفحة إلى الإشارات المرجعية” في قائمة الخيارات الإضافية.
boolean
يعرض “تنزيل الصفحة” في قائمة الخيارات الإضافية.
'system' | 'light' | 'dark'
يفرض light أو dark ذلك المظهر بصرف النظر عن إعداد النظام على الجهاز. ويتبع system إعداد النظام.
'done' | 'close' | 'cancel'
نمط زر الإغلاق. يقرر iOS ما إذا كان سيظهر كتصنيف أو كرمز.
'pageSheet' | 'fullScreen'
يعرض pageSheet (الإعداد الافتراضي) بطاقة يمكن للعميل سحبها إلى الأسفل لإغلاقها. ويغطي fullScreen الشاشة بأكملها.
boolean
يتيح طي شريط الأدوات أثناء تمرير الصفحة. ولا يظهر تأثيره إلا عندما تكون قيمة presentationStyle هي fullScreen. أما مع pageSheet، فتظل الأشرطة مثبتة بصرف النظر عن هذا الإعداد.
'system' | 'light' | 'dark'
يفرض light أو dark ذلك المظهر بصرف النظر عن إعداد النظام على الجهاز. ويتبع system إعداد النظام.
لا يتضمن iOS خيارًا للون شريط الأدوات، لأن خصائص الصبغة الأساسية SFSafariViewController مهجورة منذ iOS 26.

الأخطاء

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

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

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

ذو صلة

Mobile Integration Guide

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

Expo Boilerplate

مثال كامل على Expo مع تكامل الدفع.
آخر تعديل في ٢٦ سبتمبر ٢٠٢٦