覆盖结账 - 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 参数来自定义结账外观。主题配置支持浅色和深色模式，允许您自定义颜色、边框、文本、按钮和边框半径。

本节介绍使用结账 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 事件，以提供良好的用户体验。

最佳实践

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

故障排除

Checkout not opening

可能的原因：

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

解决方案：

验证 SDK 初始化是否在打开结账之前发生
检查控制台错误
确保结账 URL 有效且来自创建结账会话 API
验证网络连接

Events not firing

可能的原因：

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

解决方案：

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

Styling issues

可能的原因：

与应用程序样式的 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 Checkout	Inline Checkout
集成深度	页面顶部的模态框	完全嵌入页面
布局控制	限制	完全控制
品牌效果	独立于页面	无缝衔接
实施努力	较低	较高
最佳用途	快速集成，现有页面	自定义结账页面，高转换流程

使用 overlay checkout 可实现快速集成，对现有页面的更改最少。使用 inline checkout 时，您可以最大限度地控制结账体验和无缝品牌体验。

Inline Checkout

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

Checkout Sessions API

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

Webhooks

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

Integration Guide

完整指南：集成 Dodo Payments。

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

​概述

​演示

Interactive Demo

​快速开始

​分步集成指南

​API 参考

​配置

​初始化选项

​结账选项

​方法

​打开结账

​关闭结账

​检查状态

​事件

​实施选项

​包管理器安装

​CDN 实施

​主题定制

​基本主题配置

​完整主题配置

​仅浅色模式

​仅深色模式

​部分主题覆盖

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

​TypeScript 类型

​错误处理

​最佳实践

​故障排除

​启用数字钱包

​浏览器支持

​Overlay 与 Inline Checkout 的比较

​相关资源

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

概述

演示

快速开始

分步集成指南

API 参考

配置

初始化选项

结账选项

方法

打开结账

关闭结账

检查状态

事件

实施选项

包管理器安装

CDN 实施

主题定制

基本主题配置

完整主题配置

仅浅色模式

仅深色模式

部分主题覆盖

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

TypeScript 类型

错误处理

最佳实践

故障排除

启用数字钱包

浏览器支持

Overlay 与 Inline Checkout 的比较

相关资源