内嵌结账

Inline checkout 会将安全支付表单直接嵌入您的页面布局。不同于以模态框形式打开的 overlay checkout，inline checkout 会成为页面的一部分。您可以控制布局，并在 checkout 表单旁显示自己的订单摘要。

工作原理

Inline checkout 会将安全的 Dodo Payments frame 渲染到页面上的容器中。该 frame 负责收集客户信息和支付详细信息。您的页面负责显示商品、金额及其他信息。SDK 允许您的页面与 checkout frame 相互通信。 checkout 完成后，Dodo Payments 会创建 payment；如果是订阅商品，则会创建 subscription，并发送 webhook，以便您配置访问权限。

Inline checkout frame 会安全处理所有敏感支付信息，确保符合 PCI 要求，而您无需额外认证。

优质 Inline Checkout 的要素

客户需要知道他们向谁购买、购买了什么以及需要支付多少。您的实现必须包含：

标注了必需元素的 inline checkout 示例 — Example inline checkout layout showing required elements

Recurring information：如果是 recurring，请显示 recurring 的频率以及续费时需要支付的总额。如果提供 trial，请显示 trial 时长。
Item descriptions：所购买商品的描述。
Transaction totals：小计、总税额和总计，包括 currency。
Dodo Payments footer：完整的 inline checkout frame，包括包含 Dodo Payments 信息、销售条款和隐私政策的 footer。
Refund policy：如果您的 refund policy 与 Dodo Payments 标准 refund policy 不同，请提供其链接。

始终显示完整的 inline checkout frame，包括 footer。移除或隐藏法律信息会违反合规要求。

客户旅程

checkout 流程取决于 checkout session 配置。根据您的 session 配置方式，客户可能会在单个页面上看到所有信息，也可能需要经过多个步骤。

Customer opens checkout

传入 checkout URL 即可打开 inline checkout。使用 SDK events（例如 checkout.breakdown）显示和更新页面上的信息。

Customer enters their details

Inline checkout 首先要求客户输入 email address、选择 country，并在需要时输入 ZIP 或 postal code。此步骤会收集确定 taxes 和可用 payment options 所需的全部信息。您可以预填充客户详细信息并显示已保存的地址，从而简化体验。

Customer selects payment method

输入详细信息后，客户会看到可用的 payment methods 和 payment form。根据客户所在位置，选项可能包括 credit or debit card、PayPal、Apple Pay、Google Pay 以及其他本地 payment methods。如果有已保存的 payment methods，请将其显示出来，以加快 checkout。

Checkout completed

Dodo Payments 会将每笔 payment 路由到最适合该笔交易的 acquirer，以尽可能提高成功率。客户随后会进入您可以构建的成功流程。

Dodo Payments creates the payment or subscription

Dodo Payments 会创建 payment；如果是订阅商品，则会创建 subscription，并发送 webhook，以便您配置访问权限。客户使用的 payment method 会保存到账户中，用于续费或 subscription 更改。

快速开始

安装 SDK，将其初始化为 inline 模式，然后在容器元素中打开 checkout：

import { DodoPayments } from "dodopayments-checkout";

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

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

请确保页面上存在带有相应 id 的容器元素：<div id="dodo-inline-checkout"></div>。

分步集成

Install the SDK

通过 npm、yarn 或 pnpm 安装：

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK for Inline Display

初始化 SDK 并指定 displayType: 'inline'。监听 checkout.breakdown event，以使用实时税额和总额计算结果更新 UI：

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event) => {
    if (event.event_type === "checkout.breakdown") {
      const breakdown = event.data?.message;
      // Update your UI with breakdown.subTotal, breakdown.tax, breakdown.total, etc.
    }
  },
});

Create a Container Element

在 HTML 中添加一个元素，checkout frame 将注入其中：

<div id="dodo-inline-checkout"></div>

Open the Checkout

使用容器的 checkoutUrl 和 elementId 调用 DodoPayments.Checkout.open()：

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

Test Your Integration

启动开发服务器：

npm run dev

测试 checkout 流程：
- 在 inline frame 中输入 email 和地址详细信息
- 验证自定义订单摘要是否实时更新
- 使用 test credentials 测试支付流程
- 确认 redirects 正常工作

如果您在 onEvent callback 中添加了 console log，那么应在浏览器控制台中看到记录的 checkout.breakdown events。

Go Live

准备投入 production 时：

将 mode 更改为 'live'：

DodoPayments.Initialize({
  mode: "live",
  displayType: "inline",
  onEvent: (event) => {
    // Handle events
  }
});

更新 checkout URLs，使其使用 backend 中的 live checkout sessions
在 production 中测试完整流程

完整 React 示例

此示例演示如何在 inline checkout 旁实现自定义订单摘要，并使用 checkout.breakdown event 使两者保持同步：

"use client";

import { useEffect, useState } from 'react';
import { DodoPayments, CheckoutBreakdownData } from 'dodopayments-checkout';

export default function CheckoutPage() {
  const [breakdown, setBreakdown] = useState<Partial<CheckoutBreakdownData>>({});

  useEffect(() => {
    // 1. Initialize the SDK
    DodoPayments.Initialize({
      mode: 'test',
      displayType: 'inline',
      onEvent: (event) => {
        // 2. Listen for the 'checkout.breakdown' event
        if (event.event_type === "checkout.breakdown") {
          const message = event.data?.message as CheckoutBreakdownData;
          if (message) setBreakdown(message);
        }
      }
    });

    // 3. Open the checkout in the specified container
    DodoPayments.Checkout.open({
      checkoutUrl: 'https://test.checkout.dodopayments.com/session/cks_123',
      elementId: 'dodo-inline-checkout'
    });

    return () => DodoPayments.Checkout.close();
  }, []);

  const format = (amt: number | null | undefined, curr: string | null | undefined) => 
    amt != null && curr ? `${curr} ${(amt/100).toFixed(2)}` : '0.00';

  const currency = breakdown.currency ?? breakdown.finalTotalCurrency ?? '';

  return (
    <div className="flex flex-col md:flex-row min-h-screen">
      {/* Left Side - Checkout Form */}
      <div className="w-full md:w-1/2 flex items-center">
        <div id="dodo-inline-checkout" className='w-full' />
      </div>

      {/* Right Side - Custom Order Summary */}
      <div className="w-full md:w-1/2 p-8 bg-gray-50">
        <h2 className="text-2xl font-bold mb-4">Order Summary</h2>
        <div className="space-y-2">
          {breakdown.subTotal != null && (
            <div className="flex justify-between">
              <span>Subtotal</span>
              <span>{format(breakdown.subTotal, currency)}</span>
            </div>
          )}
          {breakdown.discount != null && breakdown.discount > 0 && (
            <div className="flex justify-between">
              <span>Discount</span>
              <span>{format(breakdown.discount, currency)}</span>
            </div>
          )}
          {breakdown.tax != null && (
            <div className="flex justify-between">
              <span>Tax</span>
              <span>{format(breakdown.tax, currency)}</span>
            </div>
          )}
          <hr />
          {(breakdown.finalTotal ?? breakdown.total) != null && (
            <div className="flex justify-between font-bold text-xl">
              <span>Total</span>
              <span>{format(breakdown.finalTotal ?? breakdown.total, breakdown.finalTotalCurrency ?? currency)}</span>
            </div>
          )}
        </div>
      </div>
    </div>
  );
}

API 参考

Initialize

调用 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。
`displayType`	`"inline" \| "overlay"`	Yes	必须设置为 `"inline"` 才能嵌入 checkout。
`onEvent`	`function`	Yes	用于处理 checkout events 的 callback function。

Open Checkout

在容器中打开 checkout frame：

export type FontSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
export type FontWeight = "normal" | "medium" | "bold" | "extraBold";

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

DodoPayments.Checkout.open(options);

Option	Type	Required	Description
`checkoutUrl`	`string`	Yes	来自 create checkout session API 的 checkout session URL
`elementId`	`string`	Yes	应渲染 checkout 的 DOM 元素的 `id`
`options.showTimer`	`boolean`	No	显示或隐藏 session timer。默认为 `true`。设置为 `false` 时，session 过期后会收到 `checkout.link_expired` event。
`options.showSecurityBadge`	`boolean`	No	显示或隐藏 security badge。默认为 `true`
`options.manualRedirect`	`boolean`	No	为 `true` 时，阻止 automatic redirects。Checkout 会通过 `checkout.status` 发出 payment outcome，并通过 `checkout.redirect_requested` 发出要打开的 URL，由您处理 navigation
`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

Close Checkout

以编程方式移除 checkout frame 并清理 event listeners：

DodoPayments.Checkout.close();

Check Status

检查 checkout frame 当前是否已注入：

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

Events

SDK 通过 onEvent callback 提供实时 events。对于 inline checkout，checkout.breakdown 尤其适合用于同步 UI：

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Frame has loaded
        break;
      case "checkout.form_ready":
        // Form is ready for user input
        break;
      case "checkout.breakdown":
        // Prices, taxes, or discounts updated
        break;
      case "checkout.customer_details_submitted":
        // Customer details submitted
        break;
      case "checkout.pay_button_clicked":
        // Customer clicked pay button
        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`	Checkout frame 已加载
`checkout.form_ready`	表单已准备好接受用户输入。可用此 event 隐藏 loading states
`checkout.breakdown`	Prices、taxes 或 discounts 已更新
`checkout.customer_details_submitted`	Customer details 已提交
`checkout.pay_button_clicked`	客户点击了 pay button。适用于 analytics 和 conversion funnel tracking
`checkout.redirect`	Checkout 将进行 redirect（例如跳转到 bank page）
`checkout.error`	Checkout 期间发生 error
`checkout.link_expired`	Checkout session 已过期。仅当 `showTimer` 设置为 `false` 时收到

Checkout Breakdown Data

checkout.breakdown event 会提供 pricing 和 tax 信息：

interface CheckoutBreakdownData {
  subTotal?: number;          // Amount in cents
  discount?: number;          // Amount in cents
  tax?: number;               // Amount in cents
  total?: number;             // Amount in cents
  currency?: string;          // e.g., "USD"
  finalTotal?: number;        // Final amount including adjustments
  finalTotalCurrency?: string; // Currency for the final total
}

checkout frame 加载时会触发此 event；每当 price 重新计算时也会触发，例如客户选择 country 或输入导致 tax 发生变化的 postal code 时。 Field Details：

Field	Description
`subTotal`	所有 line items 在 discounts 或 taxes 之前的总和
`discount`	所有已应用 discounts 的总值
`tax`	计算出的 tax 金额。用户与 address fields 交互时会动态更新
`total`	session base currency 中 `subTotal - discount + tax` 的结果
`currency`	ISO currency code（例如 `"USD"`），用于标准 subtotal、discount 和 tax 值。
`finalTotal`	实际向客户收取的金额。可能包含不属于基本 price breakdown 的额外 foreign exchange adjustments 或 local payment method fees。
`finalTotalCurrency`	客户实际支付所使用的 currency。如果启用了 purchasing power parity 或 local currency conversion，该值可能不同于 `currency`。

Integration Tips：

Currency Formatting：Prices 使用最小 currency unit 的整数表示，例如 USD 的 cents。对于两位小数的 currencies，在使用 Intl.NumberFormat 格式化前除以 100。JPY 等零小数 currencies 没有更小的 unit，因此不要除以 100。
Handling Initial States：checkout 首次加载时，在用户提供 billing information 或应用 code 之前，tax 和 discount 可能为 0 或 null。请妥善处理这些状态（例如显示短横线 — 或隐藏该行）。
“Final Total” 与 “Total”：total 提供标准 price calculation，而 finalTotal 才是 transaction 的真实数据来源。如果存在 finalTotal，它准确反映将从客户 card 中收取的金额。
Real-time Feedback：使用 tax field 向用户显示 taxes 正在实时计算。这会让 checkout page 更具“live”体验，并减少地址输入步骤中的阻力。

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 Inline Checkout</title>
  
  <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
  <script>
    DodoPaymentsCheckout.DodoPayments.Initialize({
      mode: "test",
      displayType: "inline",
      onEvent: (event) => {
        console.log('Checkout event:', event);
      }
    });
  </script>
</head>
<body>
  <div id="dodo-inline-checkout"></div>

  <script>
    DodoPaymentsCheckout.DodoPayments.Checkout.open({
      checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123",
      elementId: "dodo-inline-checkout"
    });
  </script>
</body>
</html>

更新 Payment Method

Inline checkout 支持为 subscriptions 更新 payment method。当客户需要为 active subscription 更新 payment method，或重新激活 on-hold subscription 时，您可以直接在页面布局中渲染更新流程。

工作原理

调用 Update Payment Method API 获取 payment_link：

// On your server. `client` is the Dodo Payments server SDK (`new DodoPayments()` from the `dodopayments` package).
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: { type: 'new', return_url: 'https://example.com/return' }
});

将返回的 payment_link 作为 checkoutUrl 传入，以打开 inline checkout：

DodoPayments.Checkout.open({
  checkoutUrl: response.payment_link,
  elementId: "dodo-inline-checkout"
});

inline frame 仅渲染 payment method collection form。客户无需离开页面即可输入新的 card details 或选择已保存的 payment method。

对于 On-Hold Subscriptions

当更新处于 on_hold status 的 subscription 的 payment method 时，Dodo Payments 会自动为任何剩余欠款创建 charge。监控 payment.succeeded 和 subscription.active webhooks，以确认重新激活。

const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: { type: 'new', return_url: 'https://example.com/return' }
});

if (response.payment_id) {
  // Charge created for remaining dues
  DodoPayments.Checkout.open({
    checkoutUrl: response.payment_link,
    elementId: "dodo-inline-checkout"
  });
}

您也可以传入带有 payment_method_id 的 type: 'existing' 到 Update Payment Method API，以使用现有的 saved payment method，而无需收集新 details。

错误处理

始终在 onEvent callback 中实现 error handling：

DodoPayments.Initialize({
  mode: "test",
  displayType: "inline",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Show user-friendly error message
    }
  }
});

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

最佳实践

Responsive Design：确保容器元素具有足够的宽度和高度。iframe 通常会扩展以填满其容器。
Synchronization：使用 checkout.breakdown event，使自定义订单摘要或 pricing tables 与用户在 checkout frame 中看到的内容保持同步。
Skeleton States：在 checkout.opened event 触发前，在容器中显示 loading indicator。
Cleanup：组件 unmount 时调用 DodoPayments.Checkout.close()，以清理 iframe 和 event listeners。

对于 dark mode 实现，请使用 #0d0d0d 作为 background color，以便与 inline checkout frame 实现最佳视觉融合。

Payment Status Validation

不要仅依赖 inline checkout events 判断 payment success 或 failure。始终使用 webhooks 和/或 polling 实现 server-side validation。

为什么 Server-Side Validation 至关重要

虽然 inline checkout events 可提供实时反馈，但不应将其作为 payment status 的唯一真实来源。网络问题、browser crashes 或用户关闭页面都可能导致 events 丢失。为确保可靠的 payment validation：

监听 webhook events - Dodo Payments 会针对 payment status changes 发送 webhooks
实现 polling mechanism - 您的 frontend 应向 server 轮询 status updates
结合两种方式 - 使用 webhooks 作为 primary source，并以 polling 作为 fallback

实现步骤

1. 监听 checkout events - 用户点击 pay 后，开始准备验证 status：

onEvent: (event) => {
  if (event.event_type === 'checkout.pay_button_clicked') {
    // Start polling your server for confirmed status
    startPolling();
  }
}

2. Poll your server - 创建一个 endpoint，检查 database 中的 payment status（由 webhooks 更新）：

// Poll every 2 seconds until status is confirmed
const interval = setInterval(async () => {
  const { status } = await fetch(`/api/payments/${paymentId}/status`).then(r => r.json());
  if (status === 'succeeded' || status === 'failed') {
    clearInterval(interval);
    handlePaymentResult(status);
  }
}, 2000);

3. Handle webhooks server-side - Dodo 发送 payment.succeeded 或 payment.failed webhooks 时更新 database。详情请参阅我们的 Webhooks documentation。

故障排除

Checkout frame is not appearing

验证 elementId 是否匹配 DOM 中实际存在的 div 的 id
确保已将 displayType: 'inline' 传入 Initialize
检查 checkoutUrl 是否有效

Taxes are not updating in my UI

确保正在监听 checkout.breakdown event
只有当用户在 checkout frame 中输入有效 country 和 postal code 后，才会计算 taxes

Digital Wallets

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

Apple Pay 快速设置

仅 inline（embedded）checkout 需要 domain verification。hosted checkout 不需要。

Apple Pay 不适用于 overlay checkout。

Apple Pay 按 domain 在 dashboard 中进行验证。

Open Wallet domains

前往 Settings → Payment Methods，然后在 Apple Pay 行中点击 Manage domains。

Payment Methods 设置中 Apple Pay 行的 Manage domains 按钮 — Open Wallet domains from the Apple Pay row

Download the domain association file

在 Wallet domains 面板中下载 association file。

包含 Download file 按钮的 Wallet domains 面板 — Download the Apple Pay domain association file

点击 Register domain，输入嵌入 inline checkout 的 domain（例如 shop.example.com），然后点击 Continue。

已输入 domain 的 Register a domain 表单 — Register the domain where you embed inline checkout

Host the file on your domain

将其托管在：

https://shop.example.com/.well-known/apple-developer-merchantid-domain-association

该文件必须通过 HTTPS 提供，可在无需 redirects 的情况下访问，并使用 Content-Type: application/octet-stream 或 text/plain 提供。

Verify the domain

点击 Verify domain。Dodo Payments 会确认文件已上线，并将您的 domain 提交给 Apple。

Verify your domain 页面，显示 association file host path 和 Verify domain 按钮 — Verify the hosted association file

Confirm it's active

当 status 显示为 Active 时，Apple Pay 已针对该 domain 启用。使用 Enabled toggle 按 domain 开启或关闭。

Wallet domains 列表，显示具有 Active Apple Pay status 和 Enabled toggles 的 domains — Verified domains show an Active status

Test the integration

在 Apple device 上打开 checkout
确认 Apple Pay button 已显示
完成一次 test transaction

Browser Support

Dodo Payments Checkout SDK 支持：

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

Inline 与 Overlay Checkout

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

Feature	Inline	Overlay
Integration depth	完全嵌入页面	位于页面上方的 modal
Layout control	完全控制	有限控制
Branding	与页面一致	独立于页面
Implementation effort	更高	更低
Best for	自定义 checkout pages、高转化流程	快速集成、现有页面

如果您希望最大程度控制 checkout 体验并保持一致的 branding，请使用 inline checkout。如果您希望以最少改动快速集成到现有页面，请使用 overlay checkout。

Overlay Checkout

使用 overlay checkout 实现快速的 modal-based 集成。

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

工作原理

优质 Inline Checkout 的要素

客户旅程

快速开始

分步集成

完整 React 示例

API 参考

Initialize

Open Checkout

Close Checkout

Check Status

Events

Checkout Breakdown Data

CDN 实现

更新 Payment Method

工作原理

对于 On-Hold Subscriptions

错误处理

最佳实践

Payment Status Validation

为什么 Server-Side Validation 至关重要

推荐架构

实现步骤

故障排除

Digital Wallets

Apple Pay 快速设置

Browser Support

Inline 与 Overlay Checkout

相关资源

Overlay Checkout

Checkout Sessions API

Webhooks

Integration Guide

​工作原理

​优质 Inline Checkout 的要素

​客户旅程

​快速开始

​分步集成

​完整 React 示例

​API 参考

​Initialize

​Open Checkout

​Close Checkout

​Check Status

​Events

​Checkout Breakdown Data

​CDN 实现

​更新 Payment Method

​工作原理

​对于 On-Hold Subscriptions

​错误处理

​最佳实践

​Payment Status Validation

​为什么 Server-Side Validation 至关重要

​推荐架构

​实现步骤

​故障排除

​Digital Wallets

​Apple Pay 快速设置

​Browser Support

​Inline 与 Overlay Checkout

​相关资源

Overlay Checkout

Checkout Sessions API

Webhooks

Integration Guide

工作原理

优质 Inline Checkout 的要素

客户旅程

快速开始

分步集成

完整 React 示例

API 参考

Initialize

Open Checkout

Close Checkout

Check Status

Events

Checkout Breakdown Data

CDN 实现

更新 Payment Method

工作原理

对于 On-Hold Subscriptions

错误处理

最佳实践

Payment Status Validation

为什么 Server-Side Validation 至关重要

推荐架构

实现步骤

故障排除

Digital Wallets

Apple Pay 快速设置

Browser Support

Inline 与 Overlay Checkout

相关资源