Inline Checkout - Dodo Payments Documentation

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

export type FontSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
export type FontWeight = "normal" | "medium" | "bold" | "extraBold";

interface CheckoutOptions {
  checkoutUrl: string;
  elementId: string; // Required for inline checkout
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
    themeConfig?: ThemeConfig;
    payButtonText?: string;
    fontSize?: FontSize;
    fontWeight?: FontWeight;
  };
}

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.
`options.showTimer`	`boolean`	No	Show or hide the checkout timer. Defaults to `true`. When disabled, you will receive the `checkout.link_expired` event when the session expires.
`options.showSecurityBadge`	`boolean`	No	Show or hide the security badge. Defaults to `true`.
`options.manualRedirect`	`boolean`	No	When enabled, the checkout will not automatically redirect after completion. Instead, you will receive `checkout.status` and `checkout.redirect_requested` events to handle the redirect yourself.
`options.themeConfig`	`ThemeConfig`	No	Custom theme configuration.
`options.payButtonText`	`string`	No	Custom text to display on the pay button.
`options.fontSize`	`FontSize`	No	Global font size for the checkout.
`options.fontWeight`	`FontWeight`	No	Global font weight for the checkout.

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"
});

You can also pass additional options to customize the checkout behavior:

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.dodopayments.com/session/cks_123",
  elementId: "dodo-inline-checkout",
  options: {
    showTimer: false,
    showSecurityBadge: false,
    manualRedirect: true,
    payButtonText: "Pay Now",
  },
});

When using manualRedirect, handle the checkout completion in your onEvent callback:

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event) => {
    if (event.event_type === "checkout.status") {
      const status = event.data?.message?.status;
      // Handle status: "succeeded", "failed", or "processing"
    }
    if (event.event_type === "checkout.redirect_requested") {
      const redirectUrl = event.data?.message?.redirect_to;
      // Redirect the customer manually
      window.location.href = redirectUrl;
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
    }
  },
});

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

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
}

Checkout Status Event Data

When manualRedirect is enabled, you receive the checkout.status event with the following data:

interface CheckoutStatusEventData {
  message: {
    status?: "succeeded" | "failed" | "processing";
  };
}

Checkout Redirect Requested Event Data

When manualRedirect is enabled, you receive the checkout.redirect_requested event with the following data:

interface CheckoutRedirectRequestedEventData {
  message: {
    redirect_to?: string;
  };
}

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>

Theme Customization

You can customize the checkout appearance by passing a themeConfig object in the options parameter when opening checkout. The theme configuration supports both light and dark modes, allowing you to customize colors, borders, text, buttons, and border radius.

Basic Theme Configuration

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#344054",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

Complete Theme Configuration

All available theme properties:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        // Background colors
        bgPrimary: "#FFFFFF",        // Primary background color
        bgSecondary: "#F9FAFB",      // Secondary background color (e.g., tabs)
        
        // Border colors
        borderPrimary: "#D0D5DD",     // Primary border color
        borderSecondary: "#6B7280",  // Secondary border color
        inputFocusBorder: "#D0D5DD", // Input focus border color
        
        // Text colors
        textPrimary: "#344054",       // Primary text color
        textSecondary: "#6B7280",    // Secondary text color
        textPlaceholder: "#667085",  // Placeholder text color
        textError: "#D92D20",        // Error text color
        textSuccess: "#10B981",      // Success text color
        
        // Button colors
        buttonPrimary: "#A6E500",           // Primary button background
        buttonPrimaryHover: "#8CC500",      // Primary button hover state
        buttonTextPrimary: "#0D0D0D",       // Primary button text color
        buttonSecondary: "#F3F4F6",         // Secondary button background
        buttonSecondaryHover: "#E5E7EB",     // Secondary button hover state
        buttonTextSecondary: "#344054",     // Secondary button text color
      },
      dark: {
        // Background colors
        bgPrimary: "#0D0D0D",
        bgSecondary: "#1A1A1A",
        
        // Border colors
        borderPrimary: "#323232",
        borderSecondary: "#D1D5DB",
        inputFocusBorder: "#323232",
        
        // Text colors
        textPrimary: "#FFFFFF",
        textSecondary: "#909090",
        textPlaceholder: "#9CA3AF",
        textError: "#F97066",
        textSuccess: "#34D399",
        
        // Button colors
        buttonPrimary: "#A6E500",
        buttonPrimaryHover: "#8CC500",
        buttonTextPrimary: "#0D0D0D",
        buttonSecondary: "#2A2A2A",
        buttonSecondaryHover: "#3A3A3A",
        buttonTextSecondary: "#FFFFFF",
      },
      radius: "8px", // Border radius for inputs, buttons, and tabs
    },
  },
});

Light Mode Only

If you only want to customize the light theme:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#000000",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Dark Mode Only

If you only want to customize the dark theme:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      dark: {
        bgPrimary: "#000000",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Partial Theme Override

You can override only specific properties. The checkout will use default values for properties you don’t specify:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        buttonPrimary: "#FF6B6B", // Only override primary button color
      },
      radius: "16px", // Override border radius
    },
  },
});

Theme Configuration with Other Options

You can combine theme configuration with other checkout options:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: true,
    showSecurityBadge: true,
    manualRedirect: false,
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

TypeScript Types

For TypeScript users, all theme configuration types are exported:

import { ThemeConfig, ThemeModeConfig } from "dodopayments-checkout";

const themeConfig: ThemeConfig = {
  light: {
    bgPrimary: "#FFFFFF",
    // ... other properties
  },
  dark: {
    bgPrimary: "#0D0D0D",
    // ... other properties
  },
  radius: "8px",
};

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.

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 like checkout.status 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:

Your server should listen to webhook events - Dodo Payments sends webhooks for payment status changes
Implement a polling mechanism - Your frontend should poll your server for status updates
Combine both approaches - Use webhooks as the primary source and polling as a fallback

Recommended Architecture

Implementation Steps

1. Listen for checkout events - When the user clicks pay, start preparing to verify the status:

onEvent: (event) => {
  if (event.event_type === 'checkout.status') {
    // Start polling your server for confirmed status
    startPolling();
  }
}

2. Poll your server - Create an endpoint that checks your database for the payment status (updated by webhooks):

// Poll every 2 seconds until status is confirmed
const interval = setInterval(async () => {
  const { status } = await fetch(`/api/payments/${paymentId}/status`).then(r => r.json());
  if (status === 'succeeded' || status === 'failed') {
    clearInterval(interval);
    handlePaymentResult(status);
  }
}, 2000);

3. Handle webhooks server-side - Update your database when Dodo sends payment.succeeded or payment.failed webhooks. See our Webhooks documentation for details.

Handling Redirects (3DS, Google Pay, UPI)

When using manualRedirect: true, certain payment methods require redirecting the user away from your page for authentication:

3D Secure (3DS) - Card authentication
Google Pay - Wallet authentication on some flows
UPI - Indian payment method redirects

When a redirect is required, you’ll receive the checkout.redirect_requested event. Redirect the user to the provided URL:

if (event.event_type === 'checkout.redirect_requested') {
  const redirectUrl = event.data?.message?.redirect_to;
  // Save payment ID before redirect, then redirect
  sessionStorage.setItem('pendingPaymentId', paymentId);
  window.location.href = redirectUrl;
}

After authentication completes (success or failure), the user returns to your page. Do not assume success just because the user returned. Instead:

Check if the user is returning from a redirect (e.g., via sessionStorage)
Start polling your server for the confirmed payment status
Show a “Verifying payment…” state while polling
Display success/failure UI based on the server-confirmed status

Always verify payment status server-side after redirects. The user returning to your page only means authentication completed—it doesn’t indicate whether the payment succeeded or failed.

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.

Enabling Apple Pay

Apple Pay allows customers to complete payments quickly and securely using their saved payment methods. When enabled, customers can launch the Apple Pay modal directly from the checkout overlay on supported devices.

Apple Pay is supported on iOS 17+, iPadOS 17+, and Safari 17+ on macOS.

To enable Apple Pay for your domain in production, follow these steps:

Download and upload the Apple Pay domain association file

Download the Apple Pay domain association file.Upload the file to your web server at /.well-known/apple-developer-merchantid-domain-association. For example, if your website is example.com, make the file available at https://example.com/well-known/apple-developer-merchantid-domain-association.

Request Apple Pay activation

Email [email protected] with the following information:

Your production domain URL (e.g., https://example.com)
Request to enable Apple Pay for your domain

You’ll receive confirmation within 1-2 working days once Apple Pay has been enabled for your domain.

Verify Apple Pay availability

After receiving confirmation, test Apple Pay in your checkout:

Open your checkout on a supported device (iOS 17+, iPadOS 17+, or Safari 17+ on macOS)
Verify that the Apple Pay button appears as a payment option
Test the complete payment flow

Apple Pay must be enabled for your domain before it will appear as a payment option in production. Contact support before going live if you plan to offer Apple Pay.

Browser Support

The Dodo Payments Checkout SDK supports the following browsers:

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

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

​Checkout Status Event Data

​Checkout Redirect Requested Event Data

​Understanding the Breakdown Event

​Implementation Options

​Package Manager Installation

​CDN Implementation

​Theme Customization

​Basic Theme Configuration

​Complete Theme Configuration

​Light Mode Only

​Dark Mode Only

​Partial Theme Override

​Theme Configuration with Other Options

​TypeScript Types

​Error Handling

​Best Practices

​Payment Status Validation

​Why Server-Side Validation is Essential

​Recommended Architecture

​Implementation Steps

​Handling Redirects (3DS, Google Pay, UPI)

​Troubleshooting

​Enabling Apple Pay

​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

Checkout Status Event Data

Checkout Redirect Requested Event Data

Understanding the Breakdown Event

Implementation Options

Package Manager Installation

CDN Implementation

Theme Customization

Basic Theme Configuration

Complete Theme Configuration

Light Mode Only

Dark Mode Only

Partial Theme Override

Theme Configuration with Other Options

TypeScript Types

Error Handling

Best Practices

Payment Status Validation

Why Server-Side Validation is Essential

Recommended Architecture

Implementation Steps

Handling Redirects (3DS, Google Pay, UPI)

Troubleshooting

Enabling Apple Pay

Browser Support

Inline vs Overlay Checkout

Related Resources