覆盖结账

Overlay checkout 会在您的页面上方打开一个 modal 窗口。Customer 在 modal 中输入 payment details，同时您的页面仍显示在后方。当他们关闭 modal 时，控制权会返回您的页面。当他们完成 payment 后，将重定向到您的 return_url。

Interactive Demo

通过我们的 live demo 查看 Overlay checkout 的实际运行效果。

快速开始

安装 SDK，完成初始化，然后使用来自 create checkout session API 的 checkout URL 打开 checkout：

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

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

分步集成

Install the SDK

通过 npm、yarn 或 pnpm 安装：

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

在应用加载时调用一次 Initialize，通常放在 main component 或 app entry point 中：

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test", // Change to 'live' for production
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.error":
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});

始终在打开 checkout 之前初始化 SDK。在应用加载时初始化一次，而不是在每次 checkout 尝试之前初始化。

Create a Checkout Button

创建一个用于打开 checkout modal 的 component：

// components/CheckoutButton.tsx
"use client";

import { Button } from "@/components/ui/button";
import { DodoPayments } from "dodopayments-checkout";
import { useEffect, useState } from "react";

export function CheckoutButton() {
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        if (event.event_type === "checkout.opened") {
          setIsLoading(false);
        }
        if (event.event_type === "checkout.error") {
          setIsLoading(false);
          console.error("Checkout error:", event.data?.message);
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    setIsLoading(true);
    try {
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123"
      });
    } catch (error) {
      console.error("Failed to open checkout:", error);
      setIsLoading(false);
    }
  };

  return (
    <Button 
      onClick={handleCheckout}
      disabled={isLoading}
    >
      {isLoading ? "Loading..." : "Checkout Now"}
    </Button>
  );
}

Add the Button to Your Page

在应用中使用 checkout button component：

// app/page.tsx
import { CheckoutButton } from "@/components/CheckoutButton";

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1>Welcome to Our Store</h1>
      <CheckoutButton />
    </main>
  );
}

Handle Redirects

创建用于处理 payment 后 checkout redirects 的页面：

// app/success/page.tsx
export default function SuccessPage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Successful</h1>
      <p>Thank you for your purchase.</p>
    </div>
  );
}

// app/failure/page.tsx
export default function FailurePage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Failed</h1>
      <p>Please try again or contact support.</p>
    </div>
  );
}

Test Your Integration

启动 development server：

npm run dev

测试 checkout flow：
- 点击 checkout button
- 确认 modal 已显示
- 使用 test credentials 测试 payment flow
- 确认 redirects 正常工作

您应该会在 browser console 中看到记录的 checkout events。

Go Live

准备投入 production 时：

将 mode 更改为 'live'：

DodoPayments.Initialize({
  mode: "live",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});

更新 checkout URLs，使其使用来自 backend 的 live checkout sessions
在 production 中测试完整 flow
监控 events 和 errors

API 参考

初始化

调用一次 Initialize 以设置 SDK：

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}

DodoPayments.Initialize(options);

Option	Type	Required	Description
`mode`	`"test" \| "live"`	Yes	Environment mode：开发环境使用 `"test"`，生产环境使用 `"live"`
`displayType`	`"overlay" \| "inline"`	No	Display type：modal checkout 使用 `"overlay"`（默认），embedded checkout 使用 `"inline"`
`onEvent`	`function`	Yes	用于处理 checkout events 的 callback function

打开 Checkout

打开 checkout modal：

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
    themeConfig?: ThemeConfig;
    payButtonText?: string;
    fontSize?: FontSize;
    fontWeight?: FontWeight;
  };
}

DodoPayments.Checkout.open(options);

Option	Type	Required	Description
`checkoutUrl`	`string`	Yes	来自 create checkout session API 的 checkout session URL
`options.showTimer`	`boolean`	No	显示或隐藏 session timer。默认为 `true`。禁用后，session 过期时会收到 `checkout.link_expired` event。
`options.showSecurityBadge`	`boolean`	No	显示或隐藏 security badge。默认为 `true`
`options.manualRedirect`	`boolean`	No	当值为 `true` 时，阻止 automatic redirects。Checkout 会发送包含 payment outcome 的 `checkout.status` 以及包含待打开 URL 的 `checkout.redirect_requested`，由您处理 navigation
`options.themeConfig`	`ThemeConfig`	No	已弃用。创建 checkout session 时改为在 server-side 配置 theme
`options.payButtonText`	`string`	No	pay button 的自定义文本
`options.fontSize`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	No	checkout 的全局 font size
`options.fontWeight`	`"normal" \| "medium" \| "bold" \| "extraBold"`	No	checkout 的全局 font weight

关闭 Checkout

以编程方式关闭 modal：

DodoPayments.Checkout.close();

检查状态

检查 modal 当前是否已打开：

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

Events

通过传递给 Initialize 的 onEvent callback 监听 checkout events：

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.form_ready":
        // Form is ready for user input
        break;
      case "checkout.payment_page_opened":
        // Payment page is displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer details submitted
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.redirect":
        // Checkout will redirect
        break;
      case "checkout.error":
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Session expired (only when showTimer is false)
        break;
    }
  }
});

Event	Description
`checkout.opened`	Modal 已打开
`checkout.form_ready`	Form 已准备好接收用户输入。可使用此 event 隐藏 loading states
`checkout.payment_page_opened`	Payment page 已显示
`checkout.customer_details_submitted`	Customer 和 billing details 已提交
`checkout.closed`	Modal 已关闭
`checkout.redirect`	Checkout 将进行 redirect（例如跳转到 bank page）
`checkout.error`	Checkout 期间发生 error
`checkout.link_expired`	Checkout session 已过期。仅当 `showTimer` 设置为 `false` 时接收。

CDN 实现

如需在不执行 build step 的情况下快速集成，请从 CDN 加载 SDK：

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

  <script>
    function openCheckout() {
      DodoPaymentsCheckout.DodoPayments.Checkout.open({
        checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123"
      });
    }
  </script>
</body>
</html>

Theme 自定义

客户端 themeConfig option 已弃用，并将在下一个 major version 的 Checkout SDK（v2.0.0）中移除。传入该 option 会在 browser console 中记录 deprecation warning。请改为通过 API 创建 checkout session 时使用 customization.theme_config parameter 配置 theme——参见 Checkout Theme Customization——或在 dashboard 的 Design page 中进行可视化配置。通过 session 配置的 themes 同样适用于 overlay、inline 和 hosted checkout。

本节介绍使用 Checkout SDK 进行已弃用的 client-side theme configuration。推荐的方法是在通过 API 创建 checkout session 时，使用 theme_config parameter 在 server-side 配置 themes。有关 API-level configuration，请参见 Checkout Theme Customization；或者在 dashboard 的 Design page 中通过 live preview 以可视化方式配置 themes。

如果必须使用 client-side theme configuration，请在 options parameter 中传入 themeConfig：

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

Theme Properties

light 和 dark modes 的所有可用 theme properties：

interface ThemeConfig {
  light?: {
    bgPrimary?: string;              // Primary background
    bgSecondary?: string;            // Secondary background (tabs, etc.)
    borderPrimary?: string;          // Primary border
    borderSecondary?: string;        // Secondary border
    textPrimary?: string;            // Primary text
    textSecondary?: string;          // Secondary text
    textPlaceholder?: string;        // Placeholder text
    textError?: string;              // Error text
    textSuccess?: string;            // Success text
    buttonPrimary?: string;          // Primary button background
    buttonPrimaryHover?: string;     // Primary button hover
    buttonTextPrimary?: string;      // Primary button text
    buttonSecondary?: string;        // Secondary button background
    buttonSecondaryHover?: string;   // Secondary button hover
    buttonTextSecondary?: string;    // Secondary button text
    inputFocusBorder?: string;       // Input focus border
  };
  dark?: {
    // Same properties as light mode
  };
  radius?: string;                   // Border radius (e.g., "8px")
}

Error Handling

始终在 onEvent callback 中实现 error handling：

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Show user-friendly error message
      // Optionally retry the checkout
    }
    if (event.event_type === "checkout.link_expired") {
      console.warn("Checkout session has expired");
      // Create a new checkout session and try again
    }
  }
});

始终处理 checkout.error event，以便在发生 errors 时提供良好的用户体验。

Best Practices

仅初始化一次：在应用加载时调用一次 Initialize，而不是在每次 checkout 之前调用
Error handling：在 event callback 中实现适当的 error handling
Test mode：开发期间使用 "test" mode，仅在准备投入 production 时切换到 "live"
Event handling：处理所有相关 events，以提供完整的用户体验
有效 URLs：始终使用来自 create checkout session API 的有效 checkout URLs
TypeScript：使用 TypeScript 以获得更好的 type safety 和 developer experience
Loading states：在 checkout 打开期间显示 loading states，以改善 UX
Timer management：如果希望手动处理 session expiration，请禁用 timer（showTimer: false）

Troubleshooting

Events not firing

可能原因：

Event handler 未正确设置
JavaScript errors 阻止了 event propagation
SDK 未正确初始化

解决方案：

确认已在 Initialize() 中正确配置 event handler
检查 browser console 中的 JavaScript errors
确认 SDK initialization 已成功完成
首先使用简单的 event handler 进行测试

Styling issues

可能原因：

CSS 与应用 styles 冲突
Theme settings 未正确应用
Responsive design issues

解决方案：

在 browser DevTools 中检查 CSS conflicts
确认 theme settings 正确
在不同 screen sizes 下测试
确保 modal 不存在 z-index conflicts

Digital Wallets

有关设置 Google Pay 和其他 digital wallets 的详细信息，请参见 Digital Wallets 页面。

Apple Pay 目前尚不支持 Overlay checkout。

Browser Support

Dodo Payments Checkout SDK 支持：

Chrome（latest）
Firefox（latest）
Safari（latest）
Edge（latest）
IE11+

Overlay 与 Inline Checkout

根据您的使用场景选择合适的 checkout type：

Feature	Overlay	Inline
Integration depth	页面上方的 Modal	完全嵌入页面
Layout control	有限	完全控制
Branding	独立于页面	与页面保持一致
Implementation effort	较低	较高
Best for	快速集成、现有页面	自定义 checkout 页面、高 conversion flow

如果希望以最少的现有页面改动实现更快集成，请使用 Overlay checkout。如果希望最大程度控制 checkout experience 并保持一致的 branding，请使用 Inline checkout。

Inline Checkout

将 checkout 直接嵌入页面，以实现完全集成的体验。

Checkout Sessions API

创建 checkout sessions，为您的 checkout experiences 提供支持。

Webhooks

使用 webhooks 在 server-side 处理 payment events。

Integration Guide

Dodo Payments 集成完整指南。

如需更多帮助，请访问我们的 Discord community，或联系我们的 developer support team。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Interactive Demo

快速开始

分步集成

API 参考

初始化

打开 Checkout

关闭 Checkout

检查状态

Events

CDN 实现

Theme 自定义

Theme Properties

Error Handling

Best Practices

Troubleshooting

Digital Wallets

Browser Support

Overlay 与 Inline Checkout

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Interactive Demo

​快速开始

​分步集成

​API 参考

​初始化

​打开 Checkout

​关闭 Checkout

​检查状态

​Events

​CDN 实现

​Theme 自定义

​Theme Properties

​Error Handling

​Best Practices

​Troubleshooting

​Digital Wallets

​Browser Support

​Overlay 与 Inline Checkout

​Related Resources

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

快速开始

分步集成

API 参考

初始化

打开 Checkout

关闭 Checkout

检查状态

Events

CDN 实现

Theme 自定义

Theme Properties

Error Handling

Best Practices

Troubleshooting

Digital Wallets

Browser Support

Overlay 与 Inline Checkout

Related Resources