نظرة عامة
تتيح لك عملية الدفع المباشر إنشاء تجارب دفع متكاملة تمامًا تتمازج بسلاسة مع موقعك الإلكتروني أو تطبيقك. على عكس الدفع المنبثق، الذي يفتح كنافذة منبثقة فوق صفحتك، يقوم الدفع المباشر بتضمين نموذج الدفع مباشرة في تخطيط صفحتك. باستخدام الدفع المباشر، يمكنك:- إنشاء تجارب دفع متكاملة تمامًا مع تطبيقك أو موقعك الإلكتروني
- السماح لـ Dodo Payments بالتقاط معلومات العملاء والدفع بشكل آمن في إطار دفع محسن
- عرض العناصر، والمجموعات، ومعلومات أخرى من Dodo Payments على صفحتك
- استخدام طرق وأحداث SDK لبناء تجارب دفع متقدمة

كيف يعمل
يعمل الدفع المباشر عن طريق تضمين إطار Dodo Payments الآمن في موقعك الإلكتروني أو تطبيقك. يتولى إطار الدفع جمع معلومات العملاء والتقاط تفاصيل الدفع. تعرض صفحتك قائمة العناصر، والمجموعات، والخيارات لتغيير ما هو موجود في عملية الدفع. يسمح لك SDK بتفاعل صفحتك مع إطار الدفع. تقوم Dodo Payments تلقائيًا بإنشاء اشتراك عند اكتمال عملية الدفع، جاهزًا للتوفير.يتولى إطار الدفع المباشر التعامل بشكل آمن مع جميع معلومات الدفع الحساسة، مما يضمن الامتثال لمعايير PCI دون الحاجة إلى شهادة إضافية من جانبك.
ما الذي يجعل الدفع المباشر جيدًا؟
من المهم أن يعرف العملاء من يشترون منه، وما الذي يشترونه، وكم يدفعون. لبناء عملية دفع مباشرة متوافقة ومحسّنة للتحويل، يجب أن تتضمن تنفيذك:
مثال على تخطيط الدفع المباشر يظهر العناصر المطلوبة
- معلومات متكررة: إذا كانت متكررة، كم مرة تتكرر والمبلغ المطلوب دفعه عند التجديد. إذا كانت تجربة مجانية، كم من الوقت تستمر التجربة.
- وصف العناصر: وصف لما يتم شراؤه.
- مجموع المعاملات: مجموع المعاملات، بما في ذلك المجموع الفرعي، والضرائب الإجمالية، والمجموع الكلي. تأكد من تضمين العملة أيضًا.
- تذييل Dodo Payments: إطار الدفع المباشر الكامل، بما في ذلك تذييل الدفع الذي يحتوي على معلومات حول Dodo Payments، وشروط البيع، وسياسة الخصوصية الخاصة بنا.
- سياسة الاسترداد: رابط إلى سياسة الاسترداد الخاصة بك، إذا كانت تختلف عن سياسة الاسترداد القياسية لـ Dodo Payments.
رحلة العميل
تحدد تكوين جلسة الدفع الخاصة بك تدفق عملية الدفع. اعتمادًا على كيفية تكوين جلسة الدفع، سيختبر العملاء عملية دفع قد تعرض جميع المعلومات في صفحة واحدة أو عبر خطوات متعددة.1
يفتح العميل عملية الدفع
يمكنك فتح الدفع الفوري عن طريق تمرير العناصر أو معاملة موجودة. استخدم SDK لعرض وتحديث المعلومات على الصفحة، وطرق SDK لتحديث العناصر بناءً على تفاعل العميل.

2
يدخل العميل تفاصيله
يطلب الدفع المباشر أولاً من العملاء إدخال عنوان بريدهم الإلكتروني، واختيار بلدهم، و(حيثما كان مطلوبًا) إدخال الرمز البريدي أو الرمز البريدي. تجمع هذه الخطوة جميع المعلومات اللازمة لتحديد الضرائب وطرق الدفع المتاحة.يمكنك ملء تفاصيل العملاء مسبقًا وعرض العناوين المحفوظة لتبسيط التجربة.
3
يختار العميل طريقة الدفع
بعد إدخال تفاصيلهم، يتم تقديم طرق الدفع المتاحة للعملاء ونموذج الدفع. قد تشمل الخيارات بطاقة ائتمان أو بطاقة خصم، PayPal، Apple Pay، Google Pay، وطرق دفع محلية أخرى بناءً على موقعهم.عرض طرق الدفع المحفوظة إذا كانت متاحة لتسريع عملية الدفع.

4
اكتملت عملية الدفع
تقوم Dodo Payments بتوجيه كل عملية دفع إلى أفضل جهة إصدار لتلك المعاملة للحصول على أفضل فرصة للنجاح. يدخل العملاء في سير عمل النجاح الذي يمكنك بناؤه.

5
Dodo Payments تنشئ اشتراكًا
تقوم Dodo Payments تلقائيًا بإنشاء اشتراك للعميل، جاهزًا للتوفير. يتم الاحتفاظ بطريقة الدفع التي استخدمها العميل في السجل للتجديدات أو تغييرات الاشتراك.

البداية السريعة
ابدأ مع الدفع الفوري من Dodo Payments في بضع أسطر من التعليمات البرمجية:دليل التكامل خطوة بخطوة
1
تثبيت SDK
قم بتثبيت SDK الدفع من Dodo Payments:
2
تهيئة SDK لعرض الدفع الفوري
قم بتهيئة SDK وحدد
displayType: 'inline'. يجب عليك أيضًا الاستماع لحدث checkout.breakdown لتحديث واجهة المستخدم الخاصة بك بحسابات الضرائب والإجماليات في الوقت الحقيقي.3
إنشاء عنصر حاوية
أضف عنصرًا إلى HTML الخاص بك حيث سيتم حقن إطار الدفع:
4
فتح الدفع
استدعاء
DodoPayments.Checkout.open() مع checkoutUrl و elementId من الحاوية الخاصة بك:5
اختبر تكاملك
- ابدأ خادم التطوير الخاص بك:
- اختبر تدفق الدفع:
- أدخل تفاصيل بريدك الإلكتروني والعنوان في الإطار الفوري.
- تحقق من أن ملخص الطلب المخصص الخاص بك يتم تحديثه في الوقت الحقيقي.
- اختبر تدفق الدفع باستخدام بيانات اعتماد الاختبار.
- تأكد من أن عمليات إعادة التوجيه تعمل بشكل صحيح.
يجب أن ترى أحداث
checkout.breakdown مسجلة في وحدة تحكم المتصفح الخاصة بك إذا قمت بإضافة سجل وحدة تحكم في رد الاتصال onEvent.6
اذهب للعيش
عندما تكون جاهزًا للإنتاج:
- غير الوضع إلى
'live':
- قم بتحديث عناوين URL للدفع الخاصة بك لاستخدام جلسات الدفع الحية من الخلفية الخاصة بك.
- اختبر التدفق الكامل في الإنتاج.
مثال كامل على React
هذا المثال يوضح كيفية تنفيذ ملخص طلب مخصص بجانب الدفع الفوري، مع الحفاظ على تزامنهم باستخدام حدثcheckout.breakdown.
مرجع API
التكوين
خيارات التهيئة
| الخيار | النوع | مطلوب | الوصف |
|---|---|---|---|
mode | "test" | "live" | نعم | وضع البيئة. |
displayType | "inline" | "overlay" | نعم | يجب تعيينه إلى "inline" لتضمين الدفع. |
onEvent | function | نعم | دالة رد الاتصال لمعالجة أحداث الدفع. |
خيارات الدفع
| الخيار | النوع | مطلوب | الوصف |
|---|---|---|---|
checkoutUrl | string | نعم | عنوان URL لجلسة الدفع. |
elementId | string | نعم | id لعنصر DOM حيث يجب عرض عملية الدفع. |
options.showTimer | boolean | لا | عرض أو إخفاء مؤقت الدفع. الافتراضي هو true. عند تعطيله، ستتلقى حدث checkout.link_expired عند انتهاء الجلسة. |
options.showSecurityBadge | boolean | لا | عرض أو إخفاء شارة الأمان. الافتراضي هو true. |
options.manualRedirect | boolean | لا | عند التمكين، لن يتم إعادة توجيه عملية الدفع تلقائيًا بعد الانتهاء. بدلاً من ذلك، ستتلقى أحداث checkout.status و checkout.redirect_requested للتعامل مع إعادة التوجيه بنفسك. |
options.payButtonText | string | لا | نص مخصص لعرضه على زر الدفع. |
الطرق
فتح الدفع
يفتح إطار الدفع في الحاوية المحددة.manualRedirect، تعامل مع إكمال الدفع في رد الاتصال onEvent الخاص بك:
إغلاق عملية الدفع
يتم إزالة إطار الدفع برمجيًا وتنظيف مستمعي الأحداث.تحقق من الحالة
يعود ما إذا كان إطار الدفع مدرجًا حاليًا.الأحداث
يوفر SDK أحداثًا في الوقت الحقيقي من خلال رد الاتصالonEvent. بالنسبة للدفع المضمن، فإن checkout.breakdown مفيد بشكل خاص لمزامنة واجهة المستخدم الخاصة بك.
| نوع الحدث | الوصف |
|---|---|
checkout.opened | تم تحميل إطار الدفع. |
checkout.breakdown | تم إطلاقه عند تحديث الأسعار أو الضرائب أو الخصومات. |
checkout.customer_details_submitted | تم تقديم تفاصيل العميل. |
checkout.redirect | ستقوم عملية الدفع بإجراء إعادة توجيه (على سبيل المثال، إلى صفحة البنك). |
checkout.error | حدث خطأ أثناء عملية الدفع. |
checkout.link_expired | تم إطلاقه عند انتهاء جلسة الدفع. يتم استلامه فقط عندما يتم تعيين showTimer إلى false. |
checkout.status | تم إطلاقه عند تمكين manualRedirect. يحتوي على حالة الدفع (succeeded، failed، أو processing). |
checkout.redirect_requested | تم إطلاقه عند تمكين manualRedirect. يحتوي على عنوان URL لإعادة توجيه العميل إليه. |
بيانات تفصيل عملية الدفع
يوفر حدثcheckout.breakdown البيانات التالية:
بيانات حدث حالة الدفع
عند تمكينmanualRedirect، ستتلقى حدث checkout.status مع البيانات التالية:
بيانات حدث إعادة توجيه الدفع المطلوبة
عند تمكينmanualRedirect، ستتلقى حدث checkout.redirect_requested مع البيانات التالية:
فهم حدث التفصيل
يعد حدثcheckout.breakdown الطريقة الأساسية لمزامنة واجهة المستخدم الخاصة بتطبيقك مع حالة دفع Dodo Payments.
عندما يتم إطلاقه:
- عند التهيئة: مباشرة بعد تحميل إطار الدفع واستعداده.
- عند تغيير العنوان: كلما اختار العميل دولة أو أدخل رمزًا بريديًا يؤدي إلى إعادة حساب الضرائب.
| الحقل | الوصف |
|---|---|
subTotal | مجموع جميع العناصر في الجلسة قبل تطبيق أي خصومات أو ضرائب. |
discount | القيمة الإجمالية لجميع الخصومات المطبقة. |
tax | مبلغ الضريبة المحسوب. في وضع inline، يتم تحديثه ديناميكيًا أثناء تفاعل المستخدم مع حقول العنوان. |
total | النتيجة الرياضية لـ subTotal - discount + tax في العملة الأساسية للجلسة. |
currency | رمز العملة ISO (مثل "USD") لقيم المجموع الفرعي القياسية والخصم والضريبة. |
finalTotal | المبلغ الفعلي الذي يتم تحصيله من العميل. قد يتضمن ذلك تعديلات إضافية على سعر الصرف أو رسوم طرق الدفع المحلية التي ليست جزءًا من تفصيل السعر الأساسي. |
finalTotalCurrency | العملة التي يدفع بها العميل فعليًا. قد تختلف هذه عن currency إذا كانت القدرة الشرائية أو تحويل العملة المحلية نشطة. |
- تنسيق العملة: يتم دائمًا إرجاع الأسعار كأعداد صحيحة في أصغر وحدة عملة (مثل السنتات للدولار الأمريكي، والين لليابان). لعرضها، قسمها على 100 (أو القوة المناسبة لـ 10) أو استخدم مكتبة تنسيق مثل
Intl.NumberFormat. - التعامل مع الحالات الأولية: عند تحميل عملية الدفع لأول مرة، قد تكون
taxوdiscountإما0أوnullحتى يقدم المستخدم معلومات الفوترة الخاصة به أو يطبق رمزًا. يجب أن تتعامل واجهة المستخدم الخاصة بك مع هذه الحالات بشكل جيد (مثل عرض شرطة—أو إخفاء الصف). - “الإجمالي النهائي” مقابل “الإجمالي”: بينما يعطيك
totalحساب السعر القياسي، فإنfinalTotalهو مصدر الحقيقة للمعاملة. إذا كانfinalTotalموجودًا، فإنه يعكس بالضبط ما سيتم تحصيله من بطاقة العميل، بما في ذلك أي تعديلات ديناميكية. - التعليقات في الوقت الحقيقي: استخدم حقل
taxلإظهار للمستخدمين أن الضرائب يتم حسابها في الوقت الحقيقي. يوفر هذا شعورًا “حيًا” لصفحة الدفع الخاصة بك ويقلل من الاحتكاك أثناء خطوة إدخال العنوان.
خيارات التنفيذ
تثبيت عبر مدير الحزم
قم بالتثبيت عبر npm أو yarn أو pnpm كما هو موضح في دليل التكامل خطوة بخطوة.تنفيذ CDN
للتكامل السريع دون خطوة بناء، يمكنك استخدام CDN الخاص بنا:تخصيص السمة
يمكنك تخصيص مظهر صفحة الدفع عن طريق تمرير كائنthemeConfig في معلمة options عند فتح صفحة الدفع. يدعم تكوين السمة كلا من الوضعين الفاتح والداكن، مما يتيح لك تخصيص الألوان، الحدود، النصوص، الأزرار، ونصف قطر الحدود.
تكوين السمة الأساسية
تكوين السمة الكامل
جميع خصائص السمة المتاحة:الوضع الفاتح فقط
إذا كنت ترغب فقط في تخصيص السمة الفاتحة:الوضع الداكن فقط
إذا كنت ترغب فقط في تخصيص السمة الداكنة:تجاوز جزئي للسمة
يمكنك تجاوز خصائص معينة فقط. ستستخدم صفحة الدفع القيم الافتراضية للخصائص التي لا تحددها:تكوين السمة مع خيارات أخرى
يمكنك دمج تكوين السمة مع خيارات الدفع الأخرى:أنواع TypeScript
لمستخدمي TypeScript، يتم تصدير جميع أنواع تكوين السمة:معالجة الأخطاء
يوفر SDK معلومات تفصيلية عن الأخطاء من خلال نظام الأحداث. تأكد دائمًا من تنفيذ معالجة الأخطاء بشكل صحيح فيonEvent:
أفضل الممارسات
- تصميم متجاوب: تأكد من أن عنصر الحاوية لديك يحتوي على عرض وارتفاع كافيين. عادةً ما يتمدد iframe لملء حاويته.
- التزامن: استخدم حدث
checkout.breakdownللحفاظ على تزامن ملخص الطلب المخصص أو جداول الأسعار مع ما يراه المستخدم في إطار الدفع. - حالات التحميل: اعرض مؤشر تحميل في حاويتك حتى يتم إطلاق حدث
checkout.opened. - التنظيف: استدعِ
DodoPayments.Checkout.close()عند تفكيك مكونك لتنظيف iframe ومستمعي الأحداث.
بالنسبة لتنفيذات الوضع الداكن، يُوصى باستخدام
#0d0d0d كلون خلفية لتحقيق تكامل بصري مثالي مع إطار الدفع المضمن.استكشاف الأخطاء وإصلاحها
إطار الدفع لا يظهر
إطار الدفع لا يظهر
- تحقق من أن
elementIdيتطابق معidلــdivالذي يوجد فعليًا في DOM. - تأكد من تمرير
displayType: 'inline'إلىInitialize. - تحقق من أن
checkoutUrlصالح.
الضرائب لا تتحدث في واجهتي
الضرائب لا تتحدث في واجهتي
- تأكد من أنك تستمع لحدث
checkout.breakdown. - يتم حساب الضرائب فقط بعد أن يدخل المستخدم دولة ورمز بريدي صالحين في إطار الدفع.
تفعيل Apple Pay
تتيح Apple Pay للعملاء إتمام المدفوعات بسرعة وأمان باستخدام طرق الدفع المحفوظة لديهم. عند التفعيل، يمكن للعملاء فتح نافذة Apple Pay مباشرة من طبقة الدفع على الأجهزة المدعومة.تدعم Apple Pay على iOS 17+ وiPadOS 17+ وSafari 17+ على macOS.
1
قم بتنزيل ورفع ملف ارتباط نطاق Apple Pay
قم بتنزيل ملف ارتباط نطاق Apple Pay.قم برفع الملف إلى خادم الويب الخاص بك في
/.well-known/apple-developer-merchantid-domain-association. على سبيل المثال، إذا كان موقعك هو example.com، اجعل الملف متاحًا في https://example.com/well-known/apple-developer-merchantid-domain-association.2
طلب تفعيل Apple Pay
أرسل بريدًا إلكترونيًا إلى [email protected] مع المعلومات التالية:
- عنوان URL لنطاق الإنتاج الخاص بك (على سبيل المثال،
https://example.com) - طلب تفعيل Apple Pay لنطاقك
ستتلقى تأكيدًا خلال 1-2 يوم عمل بمجرد تفعيل Apple Pay لنطاقك.
3
تحقق من توفر Apple Pay
بعد تلقي التأكيد، اختبر Apple Pay في صفحة الدفع الخاصة بك:
- افتح صفحة الدفع الخاصة بك على جهاز مدعوم (iOS 17+ أو iPadOS 17+ أو Safari 17+ على macOS)
- تحقق من ظهور زر Apple Pay كخيار للدفع
- اختبر تدفق الدفع الكامل
دعم المتصفح
يدعم SDK دفع Dodo Payments المتصفحات التالية:- Chrome (الأحدث)
- Firefox (الأحدث)
- Safari (الأحدث)
- Edge (الأحدث)
- IE11+
الدفع المضمن مقابل الدفع المنبثق
اختر نوع الدفع المناسب لحالتك:| الميزة | الدفع المضمن | الدفع المنبثق |
|---|---|---|
| عمق التكامل | مدمج بالكامل في الصفحة | نافذة منبثقة فوق الصفحة |
| التحكم في التخطيط | تحكم كامل | محدود |
| العلامة التجارية | سلس | منفصل عن الصفحة |
| جهد التنفيذ | أعلى | أقل |
| الأفضل لـ | صفحات دفع مخصصة، تدفقات عالية التحويل | تكامل سريع، صفحات موجودة |
الموارد ذات الصلة
الدفع المنبثق
استخدم الدفع المنبثق للتكامل السريع القائم على النوافذ المنبثقة.
API لجلسات الدفع
أنشئ جلسات دفع لتفعيل تجارب الدفع الخاصة بك.
Webhooks
تعامل مع أحداث الدفع من جانب الخادم باستخدام webhooks.
دليل التكامل
دليل كامل لتكامل Dodo Payments.