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
You can open inline checkout by passing items or an existing transaction. Use the SDK to show and update on-page information, and SDK methods to update items based on customer interaction.

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
| Option | Type | Required | Description |
|---|---|---|---|
checkoutUrl | string | Yes | عنوان URL لجلسة الخروج. |
elementId | string | Yes | id لعنصر DOM الذي يجب عرض الخروج بداخله. |
options.showTimer | boolean | No | عرض أو إخفاء مؤقت الخروج. القيمة الافتراضية هي true. عند تعطيله، ستتلقى حدث checkout.link_expired عند انتهاء الجلسة. |
options.showSecurityBadge | boolean | No | عرض أو إخفاء شارة الأمان. القيمة الافتراضية هي true. |
options.manualRedirect | boolean | No | عند تمكينه، لن يعيد الخروج التوجيه تلقائيًا بعد الإكمال. بدلًا من ذلك، ستتلقى حدثي checkout.status وcheckout.redirect_requested لتتعامل مع التوجيه بنفسك. |
options.payButtonText | string | No | نص مخصص لعرضه على زر الدفع. |
options.fontSize | FontSize | No | حجم الخط العام لواجهة الخروج. |
options.fontWeight | FontWeight | No | سمك الخط العام لواجهة الخروج. |
Methods
Open Checkout
Opens the checkout frame in the specified container.manualRedirect, handle the checkout completion in your onEvent callback:
Close Checkout
Programmatically removes the checkout frame and cleans up event listeners.Check Status
Returns whether the checkout frame is currently injected.Events
The SDK provides real-time events through theonEvent callback. For inline checkout, checkout.breakdown is particularly useful for syncing your UI.
| Event Type | Description |
|---|---|
checkout.opened | Checkout frame has been loaded. |
checkout.form_ready | Checkout form is ready to receive user input. Useful for hiding loading states and showing the checkout UI. |
checkout.breakdown | Fired when prices, taxes, or discounts are updated. |
checkout.customer_details_submitted | Customer details have been submitted. |
checkout.pay_button_clicked | Fired when the customer clicks the pay button. Useful for analytics and tracking conversion funnels. |
checkout.redirect | Checkout will perform a redirect (e.g., to a bank page). |
checkout.error | An error occurred during checkout. |
checkout.link_expired | Fired when the checkout session expires. Only received when showTimer is set to false. |
checkout.status | Fired when manualRedirect is enabled. Contains the checkout status (succeeded, failed, or processing). |
checkout.redirect_requested | Fired when manualRedirect is enabled. Contains the URL to redirect the customer to. |
Checkout Breakdown Data
Thecheckout.breakdown event provides the following data:
Checkout Status Event Data
WhenmanualRedirect is enabled, you receive the checkout.status event with the following data:
Checkout Redirect Requested Event Data
WhenmanualRedirect is enabled, you receive the checkout.redirect_requested event with the following data:
Understanding the Breakdown Event
Thecheckout.breakdown event is the primary way to keep your application’s UI in sync with the Dodo Payments checkout state.
When it fires:
- On initialization: Immediately after the checkout frame is loaded and ready.
- On address change: Whenever the customer selects a country or enters a postal code that results in a tax recalculation.
| Field | Description |
|---|---|
subTotal | The sum of all line items in the session before any discounts or taxes are applied. |
discount | The total value of all applied discounts. |
tax | The calculated tax amount. In inline mode, this updates dynamically as the user interacts with the address fields. |
total | The mathematical result of subTotal - discount + tax in the session’s base currency. |
currency | The ISO currency code (e.g., "USD") for the standard subtotal, discount, and tax values. |
finalTotal | The actual amount the customer is charged. This may include additional foreign exchange adjustments or local payment method fees that aren’t part of the basic price breakdown. |
finalTotalCurrency | The currency in which the customer is actually paying. This can differ from currency if purchasing power parity or local currency conversion is active. |
- Currency Formatting: Prices are always returned as integers in the smallest currency unit (e.g., cents for USD, yen for JPY). To display them, divide by 100 (or the appropriate power of 10) or use a formatting library like
Intl.NumberFormat. - Handling Initial States: When the checkout first loads,
taxanddiscountmay be0ornulluntil the user provides their billing information or applies a code. Your UI should handle these states gracefully (e.g., showing a dash—or hiding the row). - The “Final Total” vs “Total”: While
totalgives you the standard price calculation,finalTotalis the source of truth for the transaction. IffinalTotalis present, it reflects exactly what will be charged to the customer’s card, including any dynamic adjustments. - Real-time Feedback: Use the
taxfield to show users that taxes are being calculated in real-time. This provides a “live” feel to your checkout page and reduces friction during the address entry step.
Implementation Options
Package Manager Installation
Install via npm, yarn, or pnpm as shown in the Step-by-Step Integration Guide.CDN Implementation
For quick integration without a build step, you can use our CDN:تحديث طريقة الدفع
يدعم الخروج المضمّن تحديث طرق الدفع للاشتراكات. عندما يحتاج العميل إلى تحديث طريقة الدفع — سواء لاشتراك نشط أو لإعادة تنشيط اشتراك موقوف — يمكنك عرض تدفق التحديث مباشرةً داخل تخطيط صفحتك.كيف يعمل
- استدعِ واجهة برمجة تطبيقات تحديث طريقة الدفع للحصول على
payment_link:
- مرّر
payment_linkالتي تم إرجاعها كـcheckoutUrlلفتح الخروج المضمّن:
بالنسبة للاشتراكات الموقوفة
عند تحديث طريقة الدفع لاشتراك في الحالةon_hold، تنشئ Dodo Payments تلقائيًا رسومًا مقابل أي مستحقات متبقية. راقب خدمات الويب payment.succeeded وsubscription.active لتأكيد إعادة التنشيط.
التعامل مع الأخطاء
يقدم SDK معلومات تفصيلية عن الأخطاء عبر نظام الأحداث. نفّذ دائمًا معالجة مناسبة للأخطاء في رد نداءonEvent الخاص بك:
أفضل الممارسات
- تصميم متجاوب: تأكد من أن عنصر الحاوية لديك يحتوي على عرض وارتفاع كافيين. سيقوم الإطار المضمّن عادةً بتوسيع نفسه لملء الحاوية.
- المزامنة: استخدم حدث
checkout.breakdownلمزامنة ملخص الطلب المخصص أو جداول الأسعار مع ما يراه المستخدم في إطار الخروج. - حالات الهيكل العظمي: اعرض مؤشر تحميل في الحاوية حتى يتم إطلاق حدث
checkout.opened. - التنظيف: نادِ
DodoPayments.Checkout.close()عند إزالة المكون لتنظيف الإطار المضمّن ومستمعي الأحداث.
بالنسبة لتطبيقات الوضع الليلي، يُفضل استخدام
#0d0d0d كلون خلفية لتحقيق تكامل بصري مثالي مع إطار الخروج المضمّن.التحقق من حالة الدفع
لماذا يعتبر التحقق من جانب الخادم ضروريًا
بينما توفر أحداث الخروج المضمّن مثلcheckout.status تغذية راجعة في الوقت الفعلي، لا ينبغي أن تكون المصدر الوحيد لحقيقة حالة الدفع. يمكن أن تؤدي مشاكل الشبكة، أو تعطل المتصفح، أو إغلاق المستخدم للصفحة إلى فقد الأحداث. لضمان تحقق موثوق من الدفع:
- يجب أن يستمع خادمك إلى أحداث الويب - ترسل Dodo Payments خدمات الويب عند تغير حالات الدفع
- نفّذ آلية استطلاع - يجب أن يستعلم الواجهة الأمامية عن خادمك للحصول على تحديثات الحالة
- اجمع بين الطريقتين - استخدم خدمات الويب كمصدر أساسي والاستطلاع كحل احتياطي
البنية الموصى بها
خطوات التنفيذ
1. الاستماع إلى أحداث الخروج - عند نقر المستخدم على الدفع، ابدأ التحضير للتحقق من الحالة:payment.succeeded أو payment.failed. راجع توثيق خدمات الويب للاطلاع على التفاصيل.
التعامل مع عمليات التوجيه (3DS، Google Pay، UPI)
عند استخدامmanualRedirect: true، تتطلب بعض طرق الدفع إعادة توجيه المستخدم بعيدًا عن صفحتك للمصادقة:
- 3D Secure (3DS) - مصادقة البطاقة
- Google Pay - مصادقة المحفظة في بعض التدفقات
- UPI - إعادة توجيهات طريقة الدفع الهندية
checkout.redirect_requested. أعد توجيه المستخدم إلى عنوان URL المزود:
- تحقق مما إذا كان المستخدم يعود من إعادة توجيه (على سبيل المثال، عبر
sessionStorage) - ابدأ استطلاع خادمك للحصول على حالة الدفع المؤكدة
- عرض حالة “جاري التحقق من الدفع…” أثناء الاستطلاع
- عرض واجهة مستخدم نجاح/فشل بناءً على الحالة المؤكدة من الخادم
استكشاف الأخطاء وإصلاحها
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 مع عنوان نطاق الإنتاج الخاص بك واطلب تفعيل Apple Pay.
دعم المتصفحات
يدعم SDK الخروج من Dodo Payments المتصفحات التالية:- Chrome (الأحدث)
- Firefox (الأحدث)
- Safari (الأحدث)
- Edge (الأحدث)
- IE11+
الخروج المضمّن مقابل الخروج التراكبي
اختر نوع الخروج المناسب لحالة الاستخدام لديك:| Feature | Inline Checkout | Overlay Checkout |
|---|---|---|
| Integration depth | Fully embedded in page | Modal on top of page |
| Layout control | Full control | Limited |
| Branding | Seamless | Separate from page |
| Implementation effort | Higher | Lower |
| Best for | Custom checkout pages, high-conversion flows | Quick integration, existing pages |
الموارد ذات الصلة
Overlay Checkout
استخدم الخروج التراكبي للتكامل السريع المعتمد على النافذة المنبثقة.
Checkout Sessions API
أنشئ جلسات الخروج لتشغيل تجارب الدفع الخاصة بك.
Webhooks
تعامل مع أحداث الدفع على جانب الخادم باستخدام خدمات الويب.
Integration Guide
دليل كامل لدمج Dodo Payments.
