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

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

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

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

البداية السريعة
ابدأ مع الدفع الفوري من Dodo Payments في بضع أسطر من التعليمات البرمجية:دليل التكامل خطوة بخطوة
تهيئة SDK لعرض الدفع الفوري
قم بتهيئة SDK وحدد
displayType: 'inline'. يجب عليك أيضًا الاستماع لحدث checkout.breakdown لتحديث واجهة المستخدم الخاصة بك بحسابات الضرائب والمجموع في الوقت الحقيقي.اختبر تكاملك
- ابدأ خادم التطوير الخاص بك:
- اختبر تدفق الدفع:
- أدخل تفاصيل بريدك الإلكتروني والعنوان في الإطار الفوري.
- تحقق من أن ملخص الطلب المخصص الخاص بك يتم تحديثه في الوقت الحقيقي.
- اختبر تدفق الدفع باستخدام بيانات اعتماد الاختبار.
- تأكد من أن عمليات إعادة التوجيه تعمل بشكل صحيح.
يجب أن ترى أحداث
checkout.breakdown مسجلة في وحدة تحكم المتصفح الخاصة بك إذا قمت بإضافة سجل وحدة تحكم في رد الاتصال onEvent.مثال كامل على 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.themeConfig | ThemeConfig | لا | تكوين سمة مخصصة. |
options.payButtonText | string | لا | نص مخصص لعرضه على زر الدفع. |
options.fontSize | FontSize | لا | حجم الخط العالمي للدفع. |
options.fontWeight | FontWeight | لا | وزن الخط العالمي للدفع. |
الطرق
فتح الدفع
يفتح إطار الدفع في الحاوية المحددة.manualRedirect، تعامل مع إكمال الدفع في رد الاتصال onEvent:
إغلاق عملية الدفع
يتم إزالة إطار الدفع برمجيًا وتنظيف مستمعي الأحداث.تحقق من الحالة
يعود ما إذا كان إطار الدفع مدرجًا حاليًا.الأحداث
يوفر SDK أحداثًا في الوقت الحقيقي من خلال رد الاتصالonEvent. بالنسبة للدفع المضمن، فإن checkout.breakdown مفيد بشكل خاص لمزامنة واجهة المستخدم الخاصة بك.
| نوع الحدث | الوصف |
|---|---|
checkout.opened | تم تحميل إطار الدفع. |
checkout.breakdown | تم إطلاقه عند تحديث الأسعار أو الضرائب أو الخصومات. |
checkout.customer_details_submitted | تم تقديم تفاصيل العميل. |
checkout.pay_button_clicked | تم إطلاقه عندما ينقر العميل على زر الدفع. مفيد للتحليلات وتتبع قنوات التحويل. |
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 كلون خلفية للتكامل البصري الأمثل مع إطار الدفع المضمن.التحقق من حالة الدفع
لماذا يعتبر التحقق من صحة الخادم أمرًا أساسيًا
بينما توفر أحداث الدفع المضمنة مثلcheckout.status تعليقات في الوقت الحقيقي، يجب ألا تكون مصدر الحقيقة الوحيد لحالة الدفع. يمكن أن تتسبب مشكلات الشبكة أو تعطل المتصفح أو إغلاق المستخدم للصفحة في فقدان الأحداث. لضمان التحقق من صحة الدفع بشكل موثوق:
- يجب على خادمك الاستماع إلى أحداث webhook - ترسل Dodo Payments webhooks لتغييرات حالة الدفع
- تنفيذ آلية استطلاع - يجب على الواجهة الأمامية الخاصة بك استطلاع خادمك للحصول على تحديثات الحالة
- دمج كلا النهجين - استخدم webhooks كمصدر أساسي والاستطلاع كخيار احتياطي
الهيكل الموصى به
خطوات التنفيذ
1. الاستماع لأحداث الدفع - عندما ينقر المستخدم على الدفع، ابدأ في التحضير للتحقق من الحالة:payment.succeeded أو payment.failed webhooks. راجع وثائق webhooks للحصول على التفاصيل.
التعامل مع إعادة التوجيه (3DS، Google Pay، UPI)
عند استخدامmanualRedirect: true، تتطلب بعض طرق الدفع إعادة توجيه المستخدم بعيدًا عن صفحتك للمصادقة:
- 3D Secure (3DS) - مصادقة البطاقة
- Google Pay - مصادقة المحفظة في بعض التدفقات
- UPI - إعادة توجيه طريقة الدفع الهندية
checkout.redirect_requested. قم بإعادة توجيه المستخدم إلى عنوان URL المقدم:
- تحقق مما إذا كان المستخدم يعود من إعادة توجيه (على سبيل المثال، عبر
sessionStorage) - ابدأ في استطلاع خادمك للحصول على حالة الدفع المؤكدة
- عرض حالة “جارٍ التحقق من الدفع…” أثناء الاستطلاع
- عرض واجهة المستخدم للنجاح/الفشل بناءً على الحالة المؤكدة من الخادم
استكشاف الأخطاء وإصلاحها
إطار الدفع لا يظهر
إطار الدفع لا يظهر
- تحقق من أن
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.
قم بتنزيل ورفع ملف ارتباط نطاق Apple Pay
قم بتنزيل ملف ارتباط نطاق Apple Pay.قم بتحميل الملف إلى خادم الويب الخاص بك في
/.well-known/apple-developer-merchantid-domain-association. على سبيل المثال، إذا كان موقعك هو example.com، اجعل الملف متاحًا في https://example.com/well-known/apple-developer-merchantid-domain-association.طلب تفعيل Apple Pay
أرسل بريدًا إلكترونيًا إلى support@dodopayments.com مع المعلومات التالية:
- عنوان URL لنطاق الإنتاج الخاص بك (على سبيل المثال،
https://example.com) - طلب تمكين Apple Pay لنطاقك
ستتلقى تأكيدًا خلال 1-2 يوم عمل بمجرد تمكين Apple Pay لنطاقك.
