تغطي هذه الصفحة حزمة 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 هذه في مسار الدفع الكامل على الأجهزة المحمولة.
SFSafariViewController على iOS وCustom Tab على Android. ولا تحتوي على مفتاح API ولا على منطق دفع خاص بها، ولذلك لا تستدعي واجهة Dodo Payments البرمجية مطلقًا. يجري الدفع في نافذة المتصفح. تعرض حزمة SDK هذه النافذة وتغلقها، وتقرأ النتيجة من عنوان URL للعودة.
التثبيت
1
Install the Package
- Android
- iOS
- Expo
تُربط الحزمة تلقائيًا وتسحب يُحلّ الاعتماد الأصلي تلقائيًا، لذا لا حاجة إلى خطوات تثبيت أخرى.
com.dodopayments.api:checkout-android من Maven Central.2
Register a Callback URL Scheme
سجّل مخطط URL لكي يوجّه نظام التشغيل عنوان URL للعودة الخاص بالدفع إلى تطبيقك.في كل نظام أساسي، عيّن عنوان URL نفسه الذي تستخدمه جلسة الدفع في
- Android (Gradle)
- iOS (Info.plist)
- Expo (both platforms)
اضبط المخطط كعنصر نائب في البيان داخل استبدل
android/app/build.gradle:android/app/build.gradle
"myapp" بالمخطط الخاص بتطبيقك.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 تعترض إعادة التوجيه أصليًا. يمكنك تسجيل المستمع على كلا النظامين الأساسيين.
handleOpenURL إلى true عندما ينتمي عنوان URL إلى عملية الدفع الجارية، وإلى false لأي عنوان URL آخر.
معنى النتيجة
تنشئ حزمة SDK النتيجة من معلمات 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. تُعيّن لعمليات دفع الاشتراكات.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. يقرأ كل نظام أساسي كائنه الخاص فقط. جميع الحقول اختيارية. عند حذف حقل، يطبّق النظام الأساسي الإعداد الافتراضي الخاص به.
Android — Custom Tab
Android — Custom Tab
string
لون خلفية شريط الأدوات، كسلسلة سداسية عشرية:
"#RRGGBB" أو "#AARRGGBB".لون شريط التنقل، كسلسلة سداسية عشرية.
لون الفاصل أعلى شريط التنقل، كسلسلة سداسية عشرية.
'default' | 'back'
يعرض
default رمز “X” الخاص بالنظام. ويعرض back سهم رجوع ترسمه حزمة SDK.'start' | 'end'
الجانب من شريط الأدوات الذي يظهر فيه زر الإغلاق.
يعرض رمز المشاركة في شريط الأدوات. ويخفيه
false.boolean
يعرض عنوان الصفحة أسفل عنوان URL في شريط الأدوات.
boolean
يخفي شريط الأدوات تلقائيًا أثناء تمرير الصفحة.
boolean
يعرض “إضافة الصفحة إلى الإشارات المرجعية” في قائمة الخيارات الإضافية.
boolean
يعرض “تنزيل الصفحة” في قائمة الخيارات الإضافية.
'system' | 'light' | 'dark'
يفرض
light أو dark ذلك المظهر بصرف النظر عن إعداد النظام على الجهاز. ويتبع system إعداد النظام.iOS — SFSafariViewController
iOS — SFSafariViewController
'done' | 'close' | 'cancel'
نمط زر الإغلاق. يقرر iOS ما إذا كان سيظهر كتصنيف أو كرمز.
'pageSheet' | 'fullScreen'
يعرض
pageSheet (الإعداد الافتراضي) بطاقة يمكن للعميل سحبها إلى الأسفل لإغلاقها. ويغطي fullScreen الشاشة بأكملها.boolean
يتيح طي شريط الأدوات أثناء تمرير الصفحة. ولا يظهر تأثيره إلا عندما تكون قيمة
presentationStyle هي fullScreen. أما مع pageSheet، فتظل الأشرطة مثبتة بصرف النظر عن هذا الإعداد.'system' | 'light' | 'dark'
يفرض
light أو dark ذلك المظهر بصرف النظر عن إعداد النظام على الجهاز. ويتبع system إعداد النظام.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 مع تكامل الدفع.