跳转到主要内容

​
概述

Dodo Payments Checkout SDK 提供了一种无缝的方式将我们的支付覆盖集成到您的 Web 应用程序中。它使用 TypeScript 和现代 Web 标准构建，提供了一个强大的解决方案，用于处理实时事件处理和可自定义主题的支付。
Overlay Checkout Cover Image

​
演示

Interactive Demo

通过我们的实时演示查看覆盖式结账的实际效果。

​
快速开始

只需几行代码即可开始使用 Dodo Payments Checkout SDK： 
import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK
DodoPayments.Initialize({
  mode: "test", // 'test' or 'live'
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open checkout
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});
从 创建结账会话 API 获取结账 URL。

​
分步集成指南

1

Install the SDK

使用您喜欢的包管理器安装 Dodo Payments Checkout SDK：
npm install dodopayments-checkout
2

Initialize the SDK

在您的应用程序中初始化 SDK，通常在您的主组件或应用程序入口点：
import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test", // Change to 'live' for production
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    // Handle different events
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.error":
        // Handle errors
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});
在尝试打开结账之前务必初始化 SDK。初始化应在应用加载时只执行一次。
3

Create a Checkout Button 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(() => {
    // Initialize the SDK
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        switch (event.event_type) {
          case "checkout.opened":
            setIsLoading(false);
            break;
          case "checkout.error":
            setIsLoading(false);
            console.error("Checkout error:", event.data?.message);
            break;
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    try {
      setIsLoading(true);
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://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>
  );
}
4

Add Checkout to Your Page

在您的应用程序中使用结账按钮组件：
// 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>
  );
}
5

Handle Success and Failure Pages

创建页面以处理结账重定向：
// 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>
  );
}
6

Test Your Integration

  1. 启动您的开发服务器：
npm run dev
  1. 测试结账流程：
    • 点击结账按钮
    • 验证覆盖是否出现
    • 使用测试凭据测试支付流程
    • 确认重定向正常工作
你应该在浏览器控制台看到结账事件的日志。
7

Go Live

当您准备好进行生产时：
  1. 将模式更改为 'live':
DodoPayments.Initialize({
  mode: "live",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});
  1. 更新您的结账 URL，以使用来自后端的实时结账会话
  2. 在生产环境中测试完整流程
  3. 监控事件和错误

​
API 参考

​
配置

​
初始化选项

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}
选项类型是否必填描述
mode"test" | "live"是环境模式：'test' 用于开发，'live' 用于生产
displayType"overlay" | "inline"否显示类型：'overlay' 表示模态结账（默认），'inline' 表示嵌入式结账
onEventfunction是用于处理结账事件的回调函数

​
结账选项

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
  };
}
选项类型是否必需描述
checkoutUrlstring是来自 create checkout session API 的结账会话 URL
options.showTimerboolean否显示或隐藏倒计时。默认值为 true。当禁用时，会话过期时您将收到 checkout.link_expired 事件。
options.showSecurityBadgeboolean否显示或隐藏安全徽章。默认值为 true。

​
方法

​
打开结账

使用指定的结账会话 URL 打开结账覆盖。 
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});
您还可以传递其他选项以自定义结账行为： 
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: false,
    showSecurityBadge: false,
  },
});

​
关闭结账

以编程方式关闭结账覆盖。 
DodoPayments.Checkout.close();

​
检查状态

返回结账覆盖当前是否打开。 
const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean

​
事件

SDK 提供实时事件，您可以通过 onEvent 回调监听： 
DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.form_ready":
        // Checkout form is ready for user input
        break;
      case "checkout.payment_page_opened":
        // Payment page has been displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer and billing details submitted
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.redirect":
        // Checkout will perform a redirect
        break;
      case "checkout.error":
        // An error occurred
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Checkout session has expired (only when showTimer is false)
        break;
    }
  }
});
事件类型描述
checkout.opened结账覆盖已打开
checkout.form_ready结账表单已准备好接收用户输入。用于隐藏加载状态。
checkout.payment_page_opened支付页面已显示
checkout.customer_details_submitted客户和账单详情已提交
checkout.closed结账覆盖已关闭
checkout.redirect结账将执行重定向
checkout.error结账过程中出现错误
checkout.link_expired结账会话过期时触发。仅在 showTimer 设置为 false 时收到。

​
实施选项

​
包管理器安装

如 分步集成指南 所示，通过 npm、yarn 或 pnpm 安装。

​
CDN 实施

对于无需构建步骤的快速集成，您可以使用我们的 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 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", // Change to 'live' for production
            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://checkout.dodopayments.com/session/cks_123"
            });
        }
    </script>
</body>
</html>

​
主题定制

您可以通过在打开结账时传递一个 themeConfig 对象到 options 参数来自定义结账外观。主题配置支持浅色和深色模式，允许您自定义颜色、边框、文本、按钮和边框半径。
本节介绍使用结账 SDK 进行 客户端 主题配置。您还可以在通过 API 创建结账会话时使用 theme_config 参数进行 服务器端 配置。有关 API 级配置，请参阅 Checkout Theme Customization，或使用仪表板中的 Design page 可视化配置主题并进行实时预览。

​
基本主题配置

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

​
完整主题配置

所有可用主题属性： 
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
        
        // 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",
        
        // 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
    },
  },
});

​
仅浅色模式

如果您只想自定义浅色主题： 
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#000000",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

​
仅深色模式

如果您只想自定义深色主题： 
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      dark: {
        bgPrimary: "#000000",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

​
部分主题覆盖

您可以仅覆盖特定属性。结账将对未指定的属性使用默认值： 
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
    },
  },
});

​
与其他选项结合的主题配置

您可以将主题配置与其他结账选项结合使用： 
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: true,
    showSecurityBadge: true,
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

​
TypeScript 类型

对于 TypeScript 用户，所有主题配置类型都是导出的： 
import { ThemeConfig, ThemeModeConfig } from "dodopayments-checkout";

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

​
错误处理

SDK 通过事件系统提供详细的错误信息。请始终在您的 onEvent 回调中实现正确的错误处理： 
DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Handle error appropriately
      // You may want to show a user-friendly error message
      // or retry the checkout process
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
      console.warn("Checkout session has expired");
    }
  }
});
在错误发生时始终处理 checkout.error 事件，以提供良好的用户体验。

​
最佳实践

  1. 仅初始化一次：在应用程序加载时初始化 SDK，而不是每次尝试结账时
  2. 错误处理：始终在事件回调中实现正确的错误处理
  3. 测试模式：在开发过程中使用 test 模式，只有在准备好生产时才切换到 live
  4. 事件处理：处理所有相关事件以提供完整的用户体验
  5. 有效的 URL：始终使用来自创建结账会话 API 的有效结账 URL
  6. TypeScript：使用 TypeScript 提供更好的类型安全性和开发者体验
  7. 加载状态：在打开结账时显示加载状态以改善用户体验
  8. 计时器管理：如果您想手动处理会话过期，请禁用计时器 (showTimer: false)

​
故障排除

可能的原因：
  • 在调用 open() 之前未初始化 SDK
  • 无效的结账 URL
  • 控制台中的 JavaScript 错误
  • 网络连接问题
解决方案：
  • 验证 SDK 初始化是否在打开结账之前发生
  • 检查控制台错误
  • 确保结账 URL 有效且来自创建结账会话 API
  • 验证网络连接
可能的原因：
  • 事件处理程序未正确设置
  • JavaScript 错误阻止事件传播
  • SDK 未正确初始化
解决方案：
  • 在 Initialize() 中确认事件处理程序配置正确
  • 检查浏览器控制台中的 JavaScript 错误
  • 验证 SDK 初始化是否成功完成
  • 首先测试一个简单的事件处理程序
可能的原因：
  • 与应用程序样式的 CSS 冲突
  • 主题设置应用不正确
  • 响应式设计问题
解决方案：
  • 在浏览器开发者工具中检查 CSS 冲突
  • 验证主题设置是否正确
  • 在不同屏幕尺寸上测试
  • 确保与覆盖没有 z-index 冲突

​
启用数字钱包

有关设置 Google Pay 和其他数字钱包的详细信息，请参阅 数字钱包 页面。
Overlay checkout 尚不支持 Apple Pay。Apple Pay 支持即将推出。

​
浏览器支持

Dodo Payments Checkout SDK 支持以下浏览器：
  • Chrome (最新版本)
  • Firefox (最新版本)
  • Safari (最新版本)
  • Edge (最新版本)
  • IE11+

​
Overlay 与 Inline Checkout 的比较

根据使用情况选择正确的结账类型：
功能Overlay CheckoutInline Checkout
集成深度页面顶部的模态框完全嵌入页面
布局控制限制完全控制
品牌效果独立于页面无缝衔接
实施努力较低较高
最佳用途快速集成，现有页面自定义结账页面，高转换流程
使用 overlay checkout 可实现快速集成，对现有页面的更改最少。使用 inline checkout 时，您可以最大限度地控制结账体验和无缝品牌体验。

​
相关资源

Inline Checkout

将结账直接嵌入您的页面以实现完整的集成体验。

Checkout Sessions API

创建结账会话以支持您的结账体验。

Webhooks

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

Integration Guide

完整指南：集成 Dodo Payments。
如需更多帮助，请访问我们的 Discord 社区 或联系开发者支持团队。
Last modified on April 20, 2026