Overview
Inline checkout lets you create fully integrated checkout experiences that blend seamlessly with your website or application. Unlike the overlay checkout, which opens as a modal on top of your page, inline checkout embeds the payment form directly into your page layout. Using inline checkout, you can:- Create checkout experiences that are fully integrated with your app or website
- Let Dodo Payments securely capture customer and payment information in an optimized checkout frame
- Display items, totals, and other information from Dodo Payments on your page
- Use SDK methods and events to build advanced checkout experiences

How It Works
Inline checkout works by embedding a secure Dodo Payments frame into your website or app. The checkout frame handles collecting customer information and capturing payment details. Your page displays the items list, totals, and options for changing what’s on the checkout. The SDK lets your page and the checkout frame interact with each other. Dodo Payments automatically creates a subscription when a checkout completes, ready for you to provision.The inline checkout frame securely handles all sensitive payment information, ensuring PCI compliance without additional certification on your end.
What Makes a Good Inline Checkout?
It’s important that customers know who they’re buying from, what they’re buying, and how much they’re paying. To build an inline checkout that’s compliant and optimized for conversion, your implementation must include:
- Recurring information: If recurring, how often it recurs and the total to pay on renewal. If a trial, how long the trial lasts.
- Item descriptions: A description of what’s being purchased.
- Transaction totals: Transaction totals, including subtotal, total tax, and grand total. Be sure to include the currency too.
- Dodo Payments footer: The full inline checkout frame, including the checkout footer that has information about Dodo Payments, our terms of sale, and our privacy policy.
- Refund policy: A link to your refund policy, if it differs from the Dodo Payments standard refund policy.
Customer Journey
The checkout flow is determined by your checkout session configuration. Depending on how you configure the checkout session, customers will experience a checkout that may present all information on a single page or across multiple steps.Customer opens checkout
يمكنك فتح الدفع المضمن عن طريق تمرير العناصر أو معاملة موجودة. استخدم SDK لعرض وتحديث المعلومات على الصفحة، وطرق SDK لتحديث العناصر بناءً على تفاعل العملاء.

Customer enters their details
Inline checkout first asks customers to enter their email address, select their country, and (where required) enter their ZIP or postal code. This step gathers all necessary information to determine taxes and available payment options.You can prefill customer details and present saved addresses to streamline the experience.
Customer selects payment method
After entering their details, customers are presented with available payment methods and the payment form. Options may include credit or debit card, PayPal, Apple Pay, Google Pay, and other local payment methods based on their location.Display saved payment methods if available to speed up checkout.

Checkout completed
Dodo Payments routes every payment to the best acquirer for that sale to get the best possible chance of success. Customers enter a success workflow that you can build.

Quick Start
Get started with the Dodo Payments Inline Checkout in just a few lines of code:Step-by-Step Integration Guide
Initialize the SDK for Inline Display
Initialize the SDK and specify
displayType: 'inline'. You should also listen for the checkout.breakdown event to update your UI with real-time tax and total calculations.Open the Checkout
Call
DodoPayments.Checkout.open() with the checkoutUrl and the elementId of your container:Test Your Integration
- Start your development server:
- Test the checkout flow:
- Enter your email and address details in the inline frame.
- Verify that your custom order summary updates in real-time.
- Test the payment flow using test credentials.
- Confirm redirects work correctly.
You should see
checkout.breakdown events logged in your browser console if you added a console log in the onEvent callback.Complete React Example
This example demonstrates how to implement a custom order summary alongside the inline checkout, keeping them in sync using thecheckout.breakdown event.
API Reference
Configuration
Initialize Options
| Option | Type | Required | Description |
|---|---|---|---|
mode | "test" | "live" | Yes | Environment mode. |
displayType | "inline" | "overlay" | Yes | Must be set to "inline" to embed the checkout. |
onEvent | function | Yes | Callback function for handling checkout events. |
Checkout Options
| الخيار | النوع | مطلوب | الوصف |
|---|---|---|---|
checkoutUrl | string | نعم | عنوان جلسة الدفع. |
elementId | string | نعم | id لعنصر DOM حيث يجب عرض الدفع. |
options.showTimer | boolean | لا | إظهار أو إخفاء مؤقت الدفع. الإعداد الافتراضي true. عند التعطيل، ستتلقى حدث checkout.link_expired عند انتهاء صلاحية الجلسة. |
options.showSecurityBadge | boolean | لا | إظهار أو إخفاء شارة الأمان. الإعداد الافتراضي true. |
options.payButtonText | string | لا | نص مخصص لعرضه على زر الدفع. |
options.fontSize | FontSize | لا | حجم الخط العالمي للدفع. |
options.fontWeight | FontWeight | لا | وزن الخط العالمي للدفع. |
Methods
Open Checkout
Opens the checkout frame in the specified container.إغلاق الدفع
يزيل البرنامج الإطار الدفع وينظف مستمعي الأحداث برمجيًا.تحقق من الحالة
يعيد ما إذا كان إطار الدفع محقون حاليًا.الأحداث
يوفر SDK أحداثًا في الوقت الفعلي من خلالonEvent. يعتبر checkout.breakdown مفيدًا بشكل خاص لمزامنة واجهة المستخدم الخاصة بك.
| نوع الحدث | الوصف |
|---|---|
checkout.opened | تم تحميل إطار الدفع. |
checkout.form_ready | النموذج جاهز لاستقبال إدخال المستخدم. مفيد لإخفاء حالات التحميل وعرض واجهة المستخدم للدفع. |
checkout.breakdown | يتم إطلاقه عند تحديث الأسعار أو الضرائب أو الخصومات. |
checkout.customer_details_submitted | تم تقديم تفاصيل العميل. |
checkout.pay_button_clicked | يتم إطلاقه عندما ينقر العميل على زر الدفع. مفيد للتحليلات وتتبع قنوات التحويل. |
checkout.redirect | سينفذ الدفع إعادة توجيه (مثل الصفحة البنكية). |
checkout.error | حدث خطأ أثناء الدفع. |
checkout.link_expired | يتم إطلاقه عند انتهاء صلاحية جلسة الدفع. ستتلقاها فقط عندما تكون showTimer مضبوطة على false. |
بيانات تفصيل الدفع
يوفر حدثcheckout.breakdown البيانات التالية:
فهم حدث التفصيل
يعتبر حدثcheckout.breakdown الطريقة الرئيسية للحفاظ على مزامنة واجهة تطبيقك مع حالة الدفع Dodo Payments.
متى يتم إطلاقه:
- عند التهيئة: فور تحميل إطار الدفع وجاهزيته.
- عند تغيير العنوان: كلما اختار العميل دولة أو دخل رمز بريدي يؤدي إلى إعادة حساب الضرائب.
| الحقل | الوصف |
|---|---|
subTotal | مجموع جميع عناصر السطر في الجلسة قبل تطبيق أي خصومات أو ضرائب. |
discount | القيمة الإجمالية لجميع الخصومات المطبقة. |
tax | مبلغ الضريبة المحسوبة. في وضع inline، يتم تحديث هذا ديناميكيًا مع تفاعل المستخدم مع حقول العنوان. |
total | النتيجة الرياضية لـ subTotal - discount + tax بعملة الجلسة الأساسية. |
currency | رمز العملة ISO (مثل "USD") لقيم المجموع الفرعي القياسية والخصم والضرائب. |
finalTotal | المبلغ الفعلي الذي يتم تحميله على العميل. قد يشمل ذلك تعديلات إضافية على صرف العملات الأجنبية أو رسوم طرق الدفع المحلية التي ليست جزءًا من تحليل الأسعار الأساسي. |
finalTotalCurrency | العملة التي يدفع بها العميل فعليًا. يمكن أن تختلف عن currency إذا كان تكافؤ القوة الشرائية أو التحويل بالعملة المحلية نشطًا. |
- تنسيق العملة: يتم دائمًا إرجاع الأسعار على أنها أعداد صحيحة في أصغر وحدة عملة (مثل السنتات للدولار الأمريكي، الين للين الياباني). لعرضها، قسّم على 100 (أو القوة المناسبة للعدد 10) أو استخدم مكتبة تنسيق مثل
Intl.NumberFormat. - التعامل مع الحالات الأولية: عند تحميل الدفع لأول مرة، قد يكون
taxوdiscount0أوnullحتى يقدم المستخدم معلومات الفوترة أو يطبق رمزًا. يجب على واجهة المستخدم التعامل مع هذه الحالات بأريحية (مثل عرض شرطة—أو إخفاء الصف). - “الإجمالي النهائي” مقابل “الإجمالي”: في حين أن
totalيوفر حساب السعر القياسي،finalTotalهو مصدر الحقيقة للمعاملة. إذا كانتfinalTotalموجودة، فإنها تعكس تمامًا ما سيتم تحميله على بطاقة العميل، بما في ذلك أي تعديلات ديناميكية. - التغذية الراجعة في الوقت الفعلي: استخدم حقل
taxلإظهار أن ضرائب المستخدمين يتم حسابها في الوقت الفعلي. يوفر هذا شعورًا “مباشرًا” لصفحة الدفع الخاصة بك ويقلل الاحتكاك أثناء خطوة إدخال العنوان.
خيارات التنفيذ
تثبيت مدير الحزم
قم بالتثبيت عبر npm أو yarn أو pnpm كما هو موضح في دليل التكامل خطوة بخطوة.تنفيذ CDN
للتكامل السريع بدون خطوة البناء، يمكنك استخدام CDN الخاص بنا:تحديث طريقة الدفع
يدعم الدفع المضمن تحديث طرق الدفع للاشتراكات. عندما يحتاج العميل إلى تحديث طريقة الدفع الخاصة به — سواء لاشتراك نشط أو لإعادة تفعيل اشتراك معلق — يمكنك عرض تدفق التحديث مباشرة ضمن تخطيط صفحتك.كيف يعمل
- استدعاء API تحديث طريقة الدفع للحصول على
payment_link:
- قم بتمرير
payment_linkكcheckoutUrlلفتح الدفع المضمن:
للاشتراكات المعلقة
عند تحديث طريقة الدفع لاشتراك في حالةon_hold، فإنه ينشئ Dodo Payments تلقائيًا شحنة لأي مستحقات متبقية. راقب الإشعارات payment.succeeded وsubscription.active لتأكيد إعادة التفعيل.
التعامل مع الأخطاء
يوفر SDK معلومات خطأ مفصلة من خلال نظام الأحداث. قم دائمًا بتطبيق معالجة الأخطاء الصحيحة في رد استدعاءonEvent:
أفضل الممارسات
- التصميم التكيفي: تأكد من أن عنصر الحاوية الخاص بك لديه عرض وارتفاع كافيين. سيتوسع الإطار المضمن عادة لملء حاويته.
- التزامن: استخدم حدث
checkout.breakdownللحفاظ على ملخص الطلب أو جداول التسعير الخاصة بك متزامنة مع ما يراه المستخدم في إطار الدفع. - حالات التمويه: اعرض مؤشر التحميل في الحاوية الخاصة بك حتى يتم إطلاق حدث
checkout.opened. - التنظيف: استدعوى
DodoPayments.Checkout.close()عندما يتم إلغاء تثبيت المكون الخاص بك لتنظيف الإطار والمستمعين الأحداث.
بالنسبة لتطبيقات الوضع الداكن، يوصى باستخدام
#0d0d0d كلون الخلفية لتحقيق تكامل بصري مثالي مع إطار الدفع المضمن.التحقق من حالة الدفع
لماذا التحقق من الخادم ضروري
بينما توفر أحداث الدفع المضمنة تغذية راجعة في الوقت الفعلي، يجب ألا تكون مصدر الحقيقة الوحيد لحالة الدفع. يمكن أن تتسبب مشاكل الشبكة أو تعطل المستعرض أو إغلاق المستخدم للصفحة في عدم تلقي الأحداث. لضمان تحقق موثوق من الدفع:- يجب أن يستمع الخادم الخاص بك إلى أحداث webhook - يرسل Dodo Payments إشعارات لتغييرات حالة الدفع
- تطبيق آلية الاستطلاع - يجب ان يقوم الواجهة الأمامية الخاصة بك باستطلاع الخادم للحصول على تحديثات الحالة
- جمع بين النهجين - استخدم الإشعارات كمصدر رئيسي والاستطلاع كبديل
الهندسة المعمارية الموصى بها
خطوات التنفيذ
1. استمع لأحداث الدفع - عند النقر على المستخدم على زر الدفع، ابدأ في التحضير للتحقق من الحالة:payment.succeeded أو payment.failed. راجع وثائق الإشعارات للحصول على التفاصيل.
استكشاف الأخطاء وإصلاحها
Checkout frame is not appearing
Checkout frame is not appearing
- تحقق من أن
elementIdيطابقidلdivالذي ينتمي بالفعل إلى DOM. - تأكد من أن
displayType: 'inline'مرر إلىInitialize. - تحقق من أن
checkoutUrlصالح.
Taxes are not updating in my UI
Taxes are not updating in my UI
- تأكد من أنك تستمع لحدث
checkout.breakdown. - يتم حساب الضرائب فقط بعد أن يدخل المستخدم بلدًا ورمزًا بريديًا صالحًا في إطار الدفع.
تمكين المحافظ الرقمية
لمزيد من المعلومات التفصيلية حول إعداد Apple Pay وGoogle Pay والمحافظ الرقمية الأخرى، راجع صفحة المحافظ الرقمية.الإعداد السريع ل Apple Pay
Download domain association file
قم بتنزيل ملف اقتران نطاق Apple Pay.
Request activation
أرسل بريد إلكتروني إلى support@dodopayments.com مع عنوان URL لنطاق الإنتاج الخاص بك واطلب تفعيل Apple Pay.
دعم المتصفح
يدعم SDK الدفع Dodo المتصفحات التالية:- Chrome (الأحدث)
- Firefox (الأحدث)
- Safari (الأحدث)
- Edge (الأحدث)
- IE11+
الدفع المضمن مقابل الدفع عبر الطبقة
اختر نوع الدفع المناسب لحالتك:| الميزة | الدفع المضمن | الدفع عبر الطبقة |
|---|---|---|
| عمق التكامل | مدمج بالكامل في الصفحة | نافذة علوية على الصفحة |
| تحكم التخطيط | تحكم كامل | محدود |
| العلامة التجارية | متكامل بسلاسة | منفصل عن الصفحة |
| جهد التنفيذ | أعلى | أقل |
| الأفضل لـ | صفحات الدفع المخصصة، تدفقات التحويل العالية | التكامل السريع، الصفحات القائمة |
موارد ذات صلة
Overlay Checkout
استخدم الدفع عبر الطبقة للتكامل السريع المستند إلى النوافذ العلوية.
Checkout Sessions API
قم بإنشاء جلسات دفع لتفعيل تجارب الدفع الخاصة بك.
Webhooks
تعامل مع أحداث الدفع من جهة الخادم باستخدام الإشعارات.
Integration Guide
دليل كامل لتكامل دفع Dodo.
