Inline Checkout

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:

Inline checkout example with required elements labeled

Example inline checkout layout showing required elements

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.

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.

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

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.

Available payment methods and card details form

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

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:

import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK for inline mode
DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open checkout in a specific container
DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout" // ID of the container element
});

Ensure you have a container element with the corresponding id on your page: <div id="dodo-inline-checkout"></div>.

Step-by-Step Integration Guide

Install the SDK

Install the Dodo Payments Checkout SDK:

npm install dodopayments-checkout

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.

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event) => {
    if (event.event_type === "checkout.breakdown") {
      const breakdown = event.data?.message;
      // Update your UI with breakdown.subTotal, breakdown.tax, breakdown.total, etc.
    }
  },
});

Create a Container Element

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

<div id="dodo-inline-checkout"></div>

Open the Checkout

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

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout"
});

Test Your Integration

Start your development server:

npm run dev

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.

Go Live

When you’re ready for production:

Change the mode to 'live':

DodoPayments.Initialize({
  mode: "live",
  displayType: "inline",
  onEvent: (event) => {
    // Handle events
  }
});

Update your checkout URLs to use live checkout sessions from your backend.
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.

"use client";

import { useEffect, useState } from 'react';
import { DodoPayments, CheckoutBreakdownData } from 'dodopayments-checkout';

export default function CheckoutPage() {
  const [breakdown, setBreakdown] = useState<Partial<CheckoutBreakdownData>>({});

  useEffect(() => {
    // 1. Initialize the SDK
    DodoPayments.Initialize({
      mode: 'test',
      displayType: 'inline',
      onEvent: (event) => {
        // 2. Listen for the 'checkout.breakdown' event
        if (event.event_type === "checkout.breakdown") {
          const message = event.data?.message as CheckoutBreakdownData;
          if (message) setBreakdown(message);
        }
      }
    });

    // 3. Open the checkout in the specified container
    DodoPayments.Checkout.open({
      checkoutUrl: 'https://test.dodopayments.com/session/cks_123',
      elementId: 'dodo-inline-checkout'
    });

    return () => DodoPayments.Checkout.close();
  }, []);

  const format = (amt: number | null | undefined, curr: string | null | undefined) => 
    amt != null && curr ? `${curr} ${(amt/100).toFixed(2)}` : '0.00';

  const currency = breakdown.currency ?? breakdown.finalTotalCurrency ?? '';

  return (
    <div className="flex flex-col md:flex-row min-h-screen">
      {/* Left Side - Checkout Form */}
      <div className="w-full md:w-1/2 flex items-center">
        <div id="dodo-inline-checkout" className='w-full' />
      </div>

      {/* Right Side - Custom Order Summary */}
      <div className="w-full md:w-1/2 p-8 bg-gray-50">
        <h2 className="text-2xl font-bold mb-4">Order Summary</h2>
        <div className="space-y-2">
          {breakdown.subTotal && (
            <div className="flex justify-between">
              <span>Subtotal</span>
              <span>{format(breakdown.subTotal, currency)}</span>
            </div>
          )}
          {breakdown.discount && (
            <div className="flex justify-between">
              <span>Discount</span>
              <span>{format(breakdown.discount, currency)}</span>
            </div>
          )}
          {breakdown.tax != null && (
            <div className="flex justify-between">
              <span>Tax</span>
              <span>{format(breakdown.tax, currency)}</span>
            </div>
          )}
          <hr />
          {(breakdown.finalTotal ?? breakdown.total) && (
            <div className="flex justify-between font-bold text-xl">
              <span>Total</span>
              <span>{format(breakdown.finalTotal ?? breakdown.total, breakdown.finalTotalCurrency ?? currency)}</span>
            </div>
          )}
        </div>
      </div>
    </div>
  );
}

API Reference

Configuration

Initialize Options

interface InitializeOptions {
  mode: "test" | "live";
  displayType: "inline"; // Required for inline checkout
  onEvent: (event: CheckoutEvent) => void;
}

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

interface CheckoutOptions {
  checkoutUrl: string;
  elementId: string; // Required for inline checkout
}

Option	Type	Required	Description
`checkoutUrl`	`string`	Yes	Checkout session URL.
`elementId`	`string`	Yes	The `id` of the DOM element where the checkout should be rendered.

Methods

Open Checkout

Opens the checkout frame in the specified container.

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout"
});

Close Checkout

Programmatically removes the checkout frame and cleans up event listeners.

DodoPayments.Checkout.close();

Check Status

Returns whether the checkout frame is currently injected.

const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean

Events

The SDK provides real-time events through the onEvent callback. For inline checkout, checkout.breakdown is particularly useful for syncing your UI.

Event Type	Description
`checkout.opened`	Checkout frame has been loaded.
`checkout.breakdown`	Fired when prices, taxes, or discounts are updated.
`checkout.customer_details_submitted`	Customer details have been submitted.
`checkout.redirect`	Checkout will perform a redirect (e.g., to a bank page).
`checkout.error`	An error occurred during checkout.

Checkout Breakdown Data

The checkout.breakdown event provides the following data:

interface CheckoutBreakdownData {
  subTotal?: number;          // Amount in cents
  discount?: number;         // Amount in cents
  tax?: number;              // Amount in cents
  total?: number;            // Amount in cents
  currency?: string;         // e.g., "USD"
  finalTotal?: number;       // Final amount including adjustments
  finalTotalCurrency?: string; // Currency for the final total
}

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:

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.

Key Integration Tips:

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, 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).
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.
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:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Dodo Payments Inline Checkout</title>
    
    <!-- Load DodoPayments -->
    <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
    <script>
        // Initialize the SDK
        DodoPaymentsCheckout.DodoPayments.Initialize({
            mode: "test",
            displayType: "inline",
            onEvent: (event) => {
                console.log('Checkout event:', event);
            }
        });
    </script>
</head>
<body>
    <div id="dodo-inline-checkout"></div>

    <script>
        // Open the checkout
        DodoPaymentsCheckout.DodoPayments.Checkout.open({
            checkoutUrl: "https://test.dodopayments.com/session/cks_123",
            elementId: "dodo-inline-checkout"
        });
    </script>
</body>
</html>

TypeScript Support

The SDK is written in TypeScript and includes comprehensive type definitions.

import { DodoPayments, CheckoutEvent } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event: CheckoutEvent) => {
    // event is fully typed
    console.log(event.event_type, event.data);
  },
});

Error Handling

The SDK provides detailed error information through the event system. Always implement proper error handling in your onEvent callback:

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Handle error appropriately
    }
  }
});

Always handle the checkout.error event to provide a good user experience when issues occur.

Best Practices

Responsive Design: Ensure your container element has enough width and height. The iframe will typically expand to fill its container.
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.
Skeleton States: Show a loading indicator in your container until the checkout.opened event fires.
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.

Troubleshooting

Checkout frame is not appearing

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.

Taxes are not updating in my UI

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.

Browser Support

The Dodo Payments Checkout SDK supports the following browsers:

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)
IE11+

Apple Pay is not currently supported in the inline checkout experience. We plan to add support for Apple Pay in a future release.

Inline vs Overlay Checkout

Choose the right checkout type for your use case:

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

Use inline checkout when you want maximum control over the checkout experience and seamless branding. Use overlay checkout for faster integration with minimal changes to your existing pages.

Overlay Checkout

Use the overlay checkout for quick modal-based integration.

Checkout Sessions API

Create checkout sessions to power your checkout experiences.

Webhooks

Handle payment events server-side with webhooks.

Integration Guide

Complete guide to integrating Dodo Payments.

For more help, visit our Discord community or contact our developer support team.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Overview

How It Works

What Makes a Good Inline Checkout?

Customer Journey

Quick Start

Step-by-Step Integration Guide

Complete React Example

API Reference

Configuration

Initialize Options

Checkout Options

Methods

Open Checkout

Close Checkout

Check Status

Events

Checkout Breakdown Data

Understanding the Breakdown Event

Implementation Options

Package Manager Installation

CDN Implementation

TypeScript Support

Error Handling

Best Practices

Troubleshooting

Browser Support

Inline vs Overlay Checkout

Overlay Checkout

Checkout Sessions API

Webhooks

Integration Guide

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Overview

​How It Works

​What Makes a Good Inline Checkout?

​Customer Journey

​Quick Start

​Step-by-Step Integration Guide

​Complete React Example

​API Reference

​Configuration

​Initialize Options

​Checkout Options

​Methods

​Open Checkout

​Close Checkout

​Check Status

​Events

​Checkout Breakdown Data

​Understanding the Breakdown Event

​Implementation Options

​Package Manager Installation

​CDN Implementation

​TypeScript Support

​Error Handling

​Best Practices

​Troubleshooting

​Browser Support

​Inline vs Overlay Checkout

​Related Resources

Overlay Checkout

Checkout Sessions API

Webhooks

Integration Guide

Overview

How It Works

What Makes a Good Inline Checkout?

Customer Journey

Quick Start

Step-by-Step Integration Guide

Complete React Example

API Reference

Configuration

Initialize Options

Checkout Options

Methods

Open Checkout

Close Checkout

Check Status

Events

Checkout Breakdown Data

Understanding the Breakdown Event

Implementation Options

Package Manager Installation

CDN Implementation

TypeScript Support

Error Handling

Best Practices

Troubleshooting

Browser Support

Inline vs Overlay Checkout

Related Resources