覆盖结账 - Dodo Payments Documentation

概述

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

演示

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。

分步集成指南

Install the SDK

使用您喜欢的包管理器安装 Dodo Payments Checkout SDK：

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

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。初始化应在应用加载时只执行一次。

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

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

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

Test Your Integration

启动您的开发服务器：

npm run dev

测试结账流程：
- 点击结账按钮
- 验证覆盖是否出现
- 使用测试凭据测试支付流程
- 确认重定向正常工作

你应该在浏览器控制台看到结账事件的日志。

Go Live

当您准备好进行生产时：

将模式更改为 'live':

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

更新您的结账 URL，以使用来自后端的实时结账会话
在生产环境中测试完整流程
监控事件和错误

API 参考

配置

初始化选项

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

选项	类型	是否必填	描述
`mode`	`"test" \| "live"`	是	环境模式：`'test'` 用于开发，`'live'` 用于生产
`displayType`	`"overlay" \| "inline"`	否	显示类型：`'overlay'` 表示模态结账（默认），`'inline'` 表示嵌入式结账
`onEvent`	`function`	是	用于处理结账事件的回调函数

结账选项

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
  };
}

选项	类型	是否必需	描述
`checkoutUrl`	`string`	是	来自 create checkout session API 的结账会话 URL
`options.showTimer`	`boolean`	否	显示或隐藏倒计时。默认值为 `true`。当禁用时，会话过期时您将收到 `checkout.link_expired` 事件。
`options.showSecurityBadge`	`boolean`	否	显示或隐藏安全徽章。默认值为 `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 参数来自定义结账外观。主题配置支持浅色和深色模式，允许您自定义颜色、边框、文本、按钮和边框半径。

客户端 themeConfig 选项已弃用，并将在 Checkout SDK 的下一个主要版本（v2.0.0）中移除。传入该选项会在浏览器控制台中记录弃用警告。请改为通过 API 创建 checkout session 时使用 customization.theme_config 参数配置主题 — 请参阅 Checkout Theme Customization — 或在 dashboard 的 Design page 中进行可视化配置。通过 session 配置的主题同样适用于 overlay、inline 和 hosted checkout。

本节介绍使用 Checkout SDK 进行已弃用的客户端主题配置。推荐的方法是在通过 API 创建 checkout session 时，使用 theme_config 参数在服务端配置主题。有关 API 级别的配置，请参阅 Checkout Theme Customization，或在 dashboard 中使用 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",
    },
  },
});

部分主题覆盖

你可以只覆盖特定属性。对于未指定的属性，checkout 将使用默认值：

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

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

你可以将主题配置与其他 checkout 选项结合使用：

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 事件，以提供良好的用户体验。

最佳实践

只初始化一次：在应用加载时初始化 SDK 一次，而不是在每次 checkout 尝试时初始化
错误处理：始终在事件回调中实现适当的错误处理
测试模式：在开发期间使用 test 模式，只有在准备好上线时才切换到 live
事件处理：处理所有相关事件，以提供完整的用户体验
有效 URL：始终使用来自 create checkout session API 的有效 checkout URL
TypeScript：使用 TypeScript 以获得更好的类型安全性和开发体验
加载状态：在 checkout 打开期间显示加载状态，以改善 UX
计时器管理：如果希望手动处理 session 过期，请禁用计时器（showTimer: false）

故障排除

Checkout not opening

可能原因：

在调用 open() 前未初始化 SDK
checkout URL 无效
控制台中存在 JavaScript 错误
网络连接问题

解决方案：

确认在打开 checkout 前已完成 SDK 初始化
检查控制台错误
确保 checkout URL 有效，并且来自 create checkout session API
验证网络连接

Events not firing

可能原因：

未正确设置事件处理程序
JavaScript 错误阻止了事件传播
SDK 未正确初始化

解决方案：

确认已在 Initialize() 中正确配置事件处理程序
检查浏览器控制台中的 JavaScript 错误
验证 SDK 初始化已成功完成
先使用简单的事件处理程序进行测试

Styling issues

可能原因：

CSS 与应用样式发生冲突
主题设置未正确应用
响应式设计问题

解决方案：

在浏览器 DevTools 中检查 CSS 冲突
验证主题设置是否正确
在不同屏幕尺寸下进行测试
确保 overlay 不存在 z-index 冲突

启用数字钱包

有关设置 Google Pay 和其他数字钱包的详细信息，请参阅 Digital Wallets 页面。

overlay checkout 目前尚不支持 Apple Pay。Apple Pay 支持即将推出。

浏览器支持

Dodo Payments Checkout SDK 支持以下浏览器：

Chrome（最新版本）
Firefox（最新版本）
Safari（最新版本）
Edge（最新版本）
IE11+

Overlay 与 Inline Checkout

根据你的使用场景选择合适的 checkout 类型：

功能	Overlay Checkout	Inline Checkout
集成深度	页面上方的 Modal	完全嵌入页面
布局控制	有限	完全控制
品牌展示	与页面分离	无缝融合
实现工作量	较低	较高
适用场景	快速集成、现有页面	自定义 checkout 页面、高转化流程

如果希望以最少改动快速集成到现有页面，请使用 overlay checkout。如果希望最大限度地控制 checkout 体验并实现无缝品牌展示，请使用 inline checkout。

Inline Checkout

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

Checkout Sessions API

创建 checkout sessions，为 checkout 体验提供支持。

Webhooks

使用 webhooks 在服务端处理 payment events。

Integration Guide

Dodo Payments 集成完整指南。

如需更多帮助，请访问我们的 Discord community，或联系我们的开发者支持团队。

​概述

​演示

Interactive Demo

​快速开始

​分步集成指南

​API 参考

​配置

​初始化选项

​结账选项

​方法

​打开结账

​关闭结账

​检查状态

​事件

​实施选项

​包管理器安装

​CDN 实施

​主题定制

​基本主题配置

​完整主题配置

​仅浅色模式

​仅深色模式

​部分主题覆盖

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

​TypeScript 类型

​错误处理

​最佳实践

​故障排除

​启用数字钱包

​浏览器支持

​Overlay 与 Inline Checkout

​相关资源

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

概述

演示

快速开始

分步集成指南

API 参考

配置

初始化选项

结账选项

方法

打开结账

关闭结账

检查状态

事件

实施选项

包管理器安装

CDN 实施

主题定制

基本主题配置

完整主题配置

仅浅色模式

仅深色模式

部分主题覆盖

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

TypeScript 类型

错误处理

最佳实践

故障排除

启用数字钱包

浏览器支持

Overlay 与 Inline Checkout

相关资源