跳转到主要内容

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
Inline Checkout Cover Image

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:
Inline checkout example with required elements labeled

Example inline checkout layout showing required elements

  1. Recurring information: If recurring, how often it recurs and the total to pay on renewal. If a trial, how long the trial lasts.
  2. Item descriptions: A description of what’s being purchased.
  3. Transaction totals: Transaction totals, including subtotal, total tax, and grand total. Be sure to include the currency too.
  4. 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.
  5. Refund policy: A link to your refund policy, if it differs from the Dodo Payments standard refund policy.
Always display the complete inline checkout frame, including the footer. Removing or hiding legal information violates compliance requirements.

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.
1

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.Initial checkout page with items list and payment form
2

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.
3

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.Available payment methods and card details form
4

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.Success screen with confirmation checkmark
5

Dodo Payments creates subscription

Dodo Payments automatically creates a subscription for the customer, ready for you to provision. The payment method the customer used is held on file for renewals or subscription changes.Subscription created with webhook notification

Quick Start

Get started with the Dodo Payments Inline Checkout in just a few lines of code:
Ensure you have a container element with the corresponding id on your page: <div id="dodo-inline-checkout"></div>.

Step-by-Step Integration Guide

1

Install the SDK

Install the Dodo Payments Checkout SDK:
2

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.
3

Create a Container Element

Add an element to your HTML where the checkout frame will be injected:
4

Open the Checkout

Call DodoPayments.Checkout.open() with the checkoutUrl and the elementId of your container:
5

Test Your Integration

  1. Start your development server:
  1. 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.
6

Go Live

When you’re ready for production:
  1. Change the mode to 'live':
  1. Update your checkout URLs to use live checkout sessions from your backend.
  2. Test the complete flow in production.

Complete React Example

This example demonstrates how to implement a custom order summary alongside the inline checkout, keeping them in sync using the checkout.breakdown event.

API Reference

Configuration

Initialize Options

Checkout Options

Methods

Open Checkout

Opens the checkout frame in the specified container.
You can also pass additional options to customize the checkout behavior:

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 the onEvent callback. For inline checkout, checkout.breakdown is particularly useful for syncing your UI.

Checkout Breakdown Data

The checkout.breakdown event provides the following data:

Understanding the Breakdown Event

The checkout.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 Details: Key Integration Tips:
  1. 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.
  2. Handling Initial States: When the checkout first loads, tax and discount may be 0 or null until 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).
  3. The “Final Total” vs “Total”: While total gives you the standard price calculation, finalTotal is the source of truth for the transaction. If finalTotal is present, it reflects exactly what will be charged to the customer’s card, including any dynamic adjustments.
  4. Real-time Feedback: Use the tax field 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:

Update Payment Method

Inline checkout supports payment method updates for subscriptions. When a customer needs to update their payment method — whether for an active subscription or to reactivate an on-hold subscription — you can render the update flow directly within your page layout.

How It Works

  1. Call the Update Payment Method API to get a payment_link:
  1. Pass the returned payment_link as the checkoutUrl to open inline checkout:
The inline frame renders only the payment method collection form. Customers can enter new card details or select a saved payment method without leaving your page.

For On-Hold Subscriptions

When updating the payment method for a subscription in on_hold status, Dodo Payments automatically creates a charge for any remaining dues. Monitor the payment.succeeded and subscription.active webhooks to confirm reactivation.
You can also use an existing saved payment method instead of collecting new details by passing type: 'existing' with a payment_method_id to the Update Payment Method API.

Error Handling

The SDK provides detailed error information through the event system. Always implement proper error handling in your onEvent callback:
Always handle the checkout.error event to provide a good user experience when issues occur.

Best Practices

  1. Responsive Design: Ensure your container element has enough width and height. The iframe will typically expand to fill its container.
  2. Synchronization: Use the checkout.breakdown event to keep your custom order summary or pricing tables in sync with what the user sees in the checkout frame.
  3. Skeleton States: Show a loading indicator in your container until the checkout.opened event fires.
  4. Cleanup: Call DodoPayments.Checkout.close() when your component unmounts to clean up the iframe and event listeners.
For dark mode implementations, it’s recommended to use #0d0d0d as the background color for optimal visual integration with the inline checkout frame.

Payment Status Validation

Do not rely solely on inline checkout events to determine payment success or failure. Always implement server-side validation using webhooks and/or polling.

Why Server-Side Validation is Essential

While inline checkout events provide real-time feedback, they should not be your only source of truth for payment status. Network issues, browser crashes, or users closing the page can cause events to be missed. To ensure reliable payment validation:
  1. Your server should listen to webhook events - Dodo Payments sends webhooks for payment status changes
  2. Implement a polling mechanism - Your frontend should poll your server for status updates
  3. Combine both approaches - Use webhooks as the primary source and polling as a fallback

Implementation Steps

1. Listen for checkout events - When the user clicks pay, start preparing to verify the status:
2. Poll your server - Create an endpoint that checks your database for the payment status (updated by webhooks):
3. Handle webhooks server-side - Update your database when Dodo sends payment.succeeded or payment.failed webhooks. See our Webhooks documentation for details.

Troubleshooting

  • Verify that elementId matches the id of a div that actually exists in the DOM.
  • Ensure displayType: 'inline' was passed to Initialize.
  • Check that the checkoutUrl is valid.
  • Ensure you are listening for the checkout.breakdown event.
  • Taxes are only calculated after the user enters a valid country and postal code in the checkout frame.

Enabling Digital Wallets

For detailed information about setting up Apple Pay, Google Pay, and other digital wallets, see the Digital Wallets page.

Quick Setup for Apple Pay

仅内联(嵌入式)结账需要进行域名验证。覆盖结账、托管结账和付款链接不需要。
Apple Pay 是通过仪表板按域名验证的。
1

Open Wallet domains

前往 设置→支付方式,在 Apple Pay 行中,单击 管理域名
支付方式设置中Apple Pay行的管理域名按钮

Open Wallet domains from the Apple Pay row

2

Download the domain association file

从钱包域名面板下载关联文件。
带有下载文件按钮的钱包域名面板

Download the Apple Pay domain association file

3

Register your domain

单击 注册域名 并输入嵌入内联结账的域名(例如 shop.example.com),然后 继续
注册域名表单,其中已输入了域名

Register the domain where you embed inline checkout

4

Host the file on your domain

将其托管于:
它必须通过 HTTPS 提供,且无重定向并使用 Content-Type: application/octet-streamtext/plain 提供。
5

Verify the domain

单击 验证域名。Dodo Payments 确认文件有效并将您的域名提交至 Apple。
带有关联文件主机路径和验证域名按钮的验证域名屏幕

Verify the hosted association file

6

Confirm it's active

当状态显示为 活动 时,Apple Pay 已为该域名启用。使用 已启用 切换开关来为每个域名启用或禁用它。
钱包域名列表,显示具有活动 Apple Pay 状态和启用切换开关的域名

Verified domains show an Active status

7

Test the integration

  1. 在 Apple 设备上打开结账
  2. 验证 Apple Pay 按钮是否显示
  3. 完成测试交易

浏览器支持

Dodo Payments 结账 SDK 支持以下浏览器:
  • Chrome(最新版)
  • Firefox(最新版)
  • Safari(最新版)
  • Edge(最新版)
  • IE11+

内联结账与覆盖结账

根据您的使用案例选择合适的结账类型:
当您希望对结账体验和无缝品牌化拥有最大控制权时使用 内联结账。要快速集成并对现有页面进行最少更改,请使用 覆盖结账

相关资源

Overlay Checkout

使用覆盖结账以进行快速的基于模式的集成。

Checkout Sessions API

创建结账会话以推动您的结账体验。

Webhooks

使用 Webhooks 在服务器端处理支付事件。

Integration Guide

Dodo Payments 集成完整指南。
有关更多帮助,请访问我们的 Discord 社区 或联系开发者支持团队。
最后修改于 2026年7月9日