覆盖结账

概述

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

演示

互动演示

查看我们的实时演示中的覆盖结账。

快速开始

只需几行代码即可开始使用 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。

分步集成指南

安装 SDK

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

npm install dodopayments-checkout

初始化 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。初始化应在您的应用程序加载时进行一次。

创建结账按钮组件

创建一个打开结账覆盖的组件：

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

将结账添加到您的页面

在您的应用程序中使用结账按钮组件：

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

处理成功和失败页面

创建页面以处理结账重定向：

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

测试您的集成

启动您的开发服务器：

npm run dev

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

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

上线

当您准备好进行生产时：

将模式更改为 '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;
    manualRedirect?: boolean;
  };
}

选项	类型	必需	描述
`checkoutUrl`	`string`	是	来自创建结账会话 API 的结账会话 URL
`options.showTimer`	`boolean`	否	显示或隐藏结账计时器。默认为 `true`。禁用时，当会话过期时，您将收到 `checkout.link_expired` 事件。
`options.showSecurityBadge`	`boolean`	否	显示或隐藏安全徽章。默认为 `true`。
`options.manualRedirect`	`boolean`	否	启用时，结账完成后不会自动重定向。相反，您将收到 `checkout.status` 和 `checkout.redirect_requested` 事件，以便您自己处理重定向。

方法

打开结账

使用指定的结账会话 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,
    manualRedirect: true,
  },
});

使用 manualRedirect 时，在您的 onEvent 回调中处理结账完成：

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  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
    }
  },
});

关闭结账

以编程方式关闭结账覆盖层。

DodoPayments.Checkout.close();

检查状态

返回结账覆盖层当前是否打开。

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

事件

SDK 提供实时事件，您可以通过 onEvent 回调进行监听：

结账状态事件数据

当 manualRedirect 启用时，您将收到 checkout.status 事件，包含以下数据：

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

结账重定向请求事件数据

当 manualRedirect 启用时，您将收到 checkout.redirect_requested 事件，包含以下数据：

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

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        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;
      case "checkout.status":
        // Checkout status update (only when manualRedirect is enabled)
        const status = event.data?.message?.status;
        break;
      case "checkout.redirect_requested":
        // Redirect requested (only when manualRedirect is enabled)
        const redirectUrl = event.data?.message?.redirect_to;
        break;
    }
  }
});

事件类型	描述
`checkout.opened`	结账覆盖层已打开
`checkout.payment_page_opened`	支付页面已显示
`checkout.customer_details_submitted`	客户和账单详细信息已提交
`checkout.closed`	结账覆盖层已关闭
`checkout.redirect`	结账将执行重定向
`checkout.error`	结账过程中发生错误
`checkout.link_expired`	当结账会话过期时触发。仅在 `showTimer` 设置为 `false` 时接收。
`checkout.status`	当 `manualRedirect` 启用时触发。包含结账状态（`succeeded`， `failed`，或 `processing`）。
`checkout.redirect_requested`	当 `manualRedirect` 启用时触发。包含重定向客户的 URL。

实现选项

包管理器安装

通过 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>

TypeScript 支持

SDK 是用 TypeScript 编写的，并包含全面的类型定义。所有公共 API 都经过完全类型化，以提供更好的开发者体验和 IntelliSense 支持。

import { DodoPayments, CheckoutEvent } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    // event is fully typed
    console.log(event.event_type, event.data);
  },
});

错误处理

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 以获得更好的类型安全性和开发者体验
加载状态：在结账打开时显示加载状态以改善用户体验
手动重定向：在需要自定义控制结账后导航时使用 manualRedirect
计时器管理：如果您希望手动处理会话过期，请禁用计时器（showTimer: false）

故障排除

结账未打开

可能原因：

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

解决方案：

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

事件未触发

可能原因：

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

解决方案：

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

样式问题

可能原因：

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

解决方案：

在浏览器开发者工具中检查 CSS 冲突
验证主题设置是否正确
在不同屏幕尺寸上测试
确保覆盖层没有 z-index 冲突

启用 Apple Pay

Apple Pay 允许客户使用其保存的支付方式快速安全地完成支付。启用后，客户可以直接从支持的设备上的结账覆盖层启动 Apple Pay 模态。

Apple Pay 在 iOS 17+、iPadOS 17+ 和 macOS 上的 Safari 17+ 中受支持。

要在生产环境中为您的域启用 Apple Pay，请按照以下步骤操作：

下载并上传 Apple Pay 域关联文件

下载 Apple Pay 域关联文件。将文件上传到您的 Web 服务器，路径为 /.well-known/apple-developer-merchantid-domain-association。例如，如果您的网站是 example.com，请确保文件可在 https://example.com/well-known/apple-developer-merchantid-domain-association 访问。

请求 Apple Pay 激活

发送电子邮件至 [email protected]，提供以下信息：

您的生产域 URL（例如，https://example.com）
请求为您的域启用 Apple Pay

您将在 1-2 个工作日内收到确认，一旦为您的域启用 Apple Pay。

验证 Apple Pay 可用性

收到确认后，在您的结账中测试 Apple Pay：

在支持的设备上打开您的结账（iOS 17+、iPadOS 17+ 或 macOS 上的 Safari 17+）
验证 Apple Pay 按钮是否作为支付选项出现
测试完整的支付流程

在生产环境中，Apple Pay 必须为您的域启用，才能作为支付选项出现。如果您计划提供 Apple Pay，请在上线前联系支持。

浏览器支持

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

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

覆盖层与内嵌结账

为您的用例选择合适的结账类型：

特性	覆盖层结账	内嵌结账
集成深度	页面顶部的模态	完全嵌入页面
布局控制	有限	完全控制
品牌	与页面分开	无缝
实现工作量	较低	较高
最适合	快速集成，现有页面	自定义结账页面，高转化流程

使用 覆盖层结账 以更快的速度集成，最小化对现有页面的更改。使用 内嵌结账 当您希望对结账体验和品牌进行最大控制时。

内嵌结账

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

结账会话 API

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

Webhooks

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

集成指南

完整的 Dodo Payments 集成指南。

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

概述

演示

互动演示

快速开始

分步集成指南

API 参考

配置

初始化选项

结账选项

方法

打开结账

关闭结账

检查状态

事件

结账状态事件数据

结账重定向请求事件数据

实现选项

包管理器安装

CDN 实现

TypeScript 支持

错误处理

最佳实践

故障排除

启用 Apple Pay

浏览器支持

覆盖层与内嵌结账

相关资源

内嵌结账

结账会话 API

Webhooks

集成指南

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​概述

​演示

互动演示

​快速开始

​分步集成指南

​API 参考

​配置

​初始化选项

​结账选项

​方法

​打开结账

​关闭结账

​检查状态

​事件

​结账状态事件数据

​结账重定向请求事件数据

​实现选项

​包管理器安装

​CDN 实现

​TypeScript 支持

​错误处理

​最佳实践

​故障排除

​启用 Apple Pay

​浏览器支持

​覆盖层与内嵌结账

​相关资源

内嵌结账

结账会话 API

Webhooks

集成指南

概述

演示

快速开始

分步集成指南

API 参考

配置

初始化选项

结账选项

方法

打开结账

关闭结账

检查状态

事件

结账状态事件数据

结账重定向请求事件数据

实现选项

包管理器安装

CDN 实现

TypeScript 支持

错误处理

最佳实践

故障排除

启用 Apple Pay

浏览器支持

覆盖层与内嵌结账

相关资源