结账功能

Dodo Payments Checkout 是一个托管式支付页面，专为数字产品和 SaaS 设计。它负责货币转换、税费计算、折扣码、地址收集和支付方式选择。您可以通过 API 或 dashboard 创建 Checkout session，客户则在安全且具有品牌特色的页面上完成支付。

Checkout Sessions API

以编程方式创建 Checkout session。

Preview Checkout

在创建会话前计算价格和税费。

Payment Methods

支持的支付方式和配置。

Integration Guide

集成 Checkout 的分步指南。

通过 Checkout Sessions API 生成的 Checkout 链接不可重复使用。它们会在 24 小时后过期；如果设置了 confirm: true，则会在 15 分钟后过期。请为每位客户和每次支付尝试生成新的 session。

Adaptive Currency

Adaptive Currency 允许客户使用偏好的本地货币支付，从而提升信任度和转化率。启用后，客户会在 Checkout 页面看到货币选择器。价格会按照实时 FX 汇率转换为客户选择的货币。如果产品启用了 Purchasing Power Parity，则会转换经过 PPP 调整的价格，而不是基础价格。如果启用了 Charm Pricing，转换后的金额会舍入为类似 49.99 的整洁尾数。

要启用 Adaptive Currency，请前往 Settings → Business 并将其打开。

Adaptive Currency

支持的货币、转换费用和退款处理。

多语言 Checkout

Checkout 支持 22 种语言。客户可以直接在页面上切换语言，UI 文本、标签和系统消息都会进行本地化。

支持的语言

语言	代码
阿拉伯语	`ar`
加泰罗尼亚语	`ca`
中文	`zh`
荷兰语	`nl`
英语	`en`
法语	`fr`
格鲁吉亚语	`ka`
德语	`de`
希伯来语	`he`
印度尼西亚语	`id`
意大利语	`it`
日语	`ja`
韩语	`ko`
马来语	`ms`
波兰语	`pl`
葡萄牙语	`pt`
罗马尼亚语	`ro`
俄语	`ru`
西班牙语	`es`
瑞典语	`sv`
泰语	`th`
土耳其语	`tr`

要强制使用特定语言，请在创建 Checkout session 时设置 customization.force_language。详情请参阅 Checkout Sessions API。

自动税费计算

系统会根据客户的账单地址自动计算税费，确保符合 GST、VAT 和销售税要求。税务规则会在适用时根据客户所在的国家和地区应用。当客户更改国家或更新地址时，税费金额会自动更新。最终的税费明细会在支付前清晰显示。

税费计算完全自动化。对于标准数字商品和 SaaS 产品，无需手动配置。

Business Tax ID 支持

对于 B2B 交易，Checkout 允许客户输入其 Business Tax ID（例如 VAT 或 GST 编号）。输入后，系统会实时验证该税号，并自动应用适用的税收豁免或反向征税规则。

折扣码

客户可以使用您在 dashboard 中创建的折扣码或促销码。折扣会即时验证，并显示更新后的价格。当产品启用 Purchasing Power Parity 后，折扣会应用于经过 PPP 调整的价格，而不是基础价格。

您可以预先应用折扣码，或通过 API 启用折扣输入字段：

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  discount_codes: ['WELCOME20'], // Pre-apply one or more codes (max 20)
  feature_flags: {
    allow_discount_code: true // Shown by default; set to false to hide the field
  },
  return_url: 'https://yoursite.com/return'
});

discount_codes 接受一个最多包含 20 个代码的数组，并按顺序叠加使用。单数形式的 discount_code 字段已弃用，但为了向后兼容仍然有效。

Discount Codes

创建和管理折扣码。

Validate Discount by Code

使用代码名称查找和验证折扣。

智能地址收集

Checkout 支持灵活的地址输入，在速度、准确性和全球覆盖范围之间取得平衡。

选项

选项	描述
Google 地址自动填充	通过自动补全快速选择
手动输入	完整地址的全面控制
国家/地区选择	税务和合规逻辑所必需
最简地址模式	在税务要求的情况下仅收集国家/地区和 ZIP

最简地址模式

为了最大限度地提高转化率，请启用最简地址收集，以减少 Checkout 阻力。当 minimal_address 设置为 true 时，Checkout 仅收集：

国家/地区 — 税费确定始终需要
ZIP/邮政编码 — 仅在销售税、VAT 或 GST 计算需要的地区收集

所有其他地址字段都会跳过。

最简地址模式，仅在 Checkout 页面显示国家/地区和 ZIP/邮政编码字段

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  minimal_address: true,
  return_url: 'https://yoursite.com/return'
});

完整地址收集为默认设置。对于不需要完整账单详情的数字产品和 SaaS 流程，请启用 minimal_address。

电话号码收集

控制 Checkout 页面是否显示电话号码字段，以及该字段是否为必填项。

标志	默认值	行为
`allow_phone_number_collection`	`true`	显示电话号码字段
`require_phone_number`	`false`	将电话号码字段设为必填

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  feature_flags: {
    allow_phone_number_collection: true,
    require_phone_number: true
  },
  return_url: 'https://yoursite.com/return'
});

require_phone_number: true 需要 allow_phone_number_collection: true。API 会拒绝电话号码收集已禁用但电话号码设为必填的 session。

自定义字段

通过定义自定义表单字段，在 Checkout 期间收集客户的其他信息。这适用于收集公司名称、团队规模、推荐来源或其他业务特定数据。

可用字段类型

类型	描述
`text`	单行文本输入
`number`	数字输入
`email`	带验证的电子邮件地址
`url`	带验证的 URL
`date`	日期选择器
`dropdown`	从预定义选项中选择
`boolean`	是/否切换

示例

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  custom_fields: [
    {
      key: 'company_name',
      label: 'Company Name',
      field_type: 'text',
      required: true
    },
    {
      key: 'team_size',
      label: 'Team Size',
      field_type: 'dropdown',
      required: true,
      options: ['1-10', '11-50', '51-200', '200+']
    }
  ],
  return_url: 'https://yoursite.com/return'
});

客户的回答会自动包含在 webhook payload（payment.succeeded、subscription.active）以及 API 响应的 custom_field_responses 数组中。每个 Checkout session 最多可以定义 5 个自定义字段。

Custom Fields Guide

自定义字段配置和响应访问方式。

隐私政策与条款接受

为确保法律和合规透明度：

Checkout 页面会清晰显示 Privacy Policy 和 Buyer Terms 链接
客户必须在完成支付前明确确认这些内容

这有助于满足包括 GDPR 合规在内的全球消费者保护和数据隐私要求。

产品集合

Product Collections 提供统一的 Checkout 体验，让客户可以在一次 Checkout 中查看并选择多个相关产品（例如 Starter、Pro 和 Enterprise 方案）。使用集合时，集合中的所有有效产品都会显示。第一个产品会被预先选中，客户可以比较选项后再进行选择。

const session = await client.checkoutSessions.create({
  product_collection_id: 'pdc_abc123',
  product_cart: [], // Required: pass an empty array for collection checkout
  return_url: 'https://yoursite.com/return'
});

使用 product_collection_id 时，请传入空的 product_cart 数组。无法在创建 session 时预先应用折扣码。

Product Collections

创建和管理产品集合。

Checkout Session 配置

使用 Checkout Sessions API 控制 Checkout 行为：

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'Jane Doe'
  },
  billing_currency: 'EUR',
  discount_codes: ['PROMO10'],
  feature_flags: {
    allow_discount_code: true
  },
  return_url: 'https://yoursite.com/return',
  cancel_url: 'https://yoursite.com/pricing',
  metadata: {
    order_ref: 'ORD-12345'
  }
});

支付完成后，客户会被重定向到您的 return_url，并自动附加 query parameters ——包括 payment_id 或 subscription_id、status、email，以及 license_key（如适用）。完整列表请参阅 Checkout Sessions guide。

Checkout Sessions API

Checkout session 的完整 API reference。

Checkout Integration Guide

集成 Checkout 的分步指南。

主题自定义

使用 customization.theme_config 参数自定义 Checkout 页面外观，使其与您的品牌保持一致。您可以为浅色和深色模式配置颜色、字体、边框圆角和按钮文本。本节介绍 server-side API，该 API 使用 bg_primary 等属性名称。在 session 上设置的主题适用于 hosted、overlay 和 inline Checkout。Checkout SDK 的 client-side themeConfig 选项使用 bgPrimary 等属性名称，现已弃用。请参阅 Overlay Checkout。

Design & Theme Customization

从 dashboard 直观配置主题，包括预构建主题、排版、颜色和实时预览。

主题配置选项

属性	描述
`light`	浅色模式的颜色配置
`dark`	深色模式的颜色配置
`font_primary_url`	主字体的 URL
`font_secondary_url`	次要字体的 URL
`font_size`	字体大小：`xs`、`sm`、`md`、`lg`、`xl`、`2xl`
`font_weight`	字体粗细：`normal`、`medium`、`bold`、`extraBold`
`radius`	UI 元素的边框圆角（例如 `4px`、`0.5rem`、`8px`）
`pay_button_text`	支付按钮的自定义文本（例如“Complete Purchase”“Subscribe Now”）

颜色配置（浅色/深色模式）

每种模式都支持以下颜色属性：

属性	描述
`bg_primary`	主要背景颜色
`bg_secondary`	次要背景颜色
`text_primary`	主要文本颜色
`text_secondary`	次要文本颜色
`text_placeholder`	文本占位符颜色
`text_error`	错误文本颜色
`text_success`	成功文本颜色
`border_primary`	主要边框颜色
`border_secondary`	次要边框颜色
`button_primary`	主按钮背景颜色
`button_primary_hover`	主按钮悬停颜色
`button_secondary`	次要按钮背景颜色
`button_secondary_hover`	次要按钮悬停颜色
`button_text_primary`	主按钮文本颜色
`button_text_secondary`	次要按钮文本颜色
`input_focus_border`	输入框聚焦边框颜色

所有颜色字段都接受标准 CSS 颜色格式：

Hex：#fff、#ffffff、#ffffffff
RGB/RGBA：rgb(255, 255, 255)、rgba(255, 255, 255, 0.5)
HSL/HSLA：hsl(120, 100%, 50%)、hsla(120, 100%, 50%, 0.5)
命名颜色：red、blue、transparent

示例

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  customization: {
    theme_config: {
      font_primary_url: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap',
      font_size: 'md',
      font_weight: 'medium',
      radius: '8px',
      pay_button_text: 'Complete Purchase',
      light: {
        bg_primary: '#ffffff',
        bg_secondary: '#f5f5f5',
        text_primary: '#1a1a1a',
        text_secondary: '#666666',
        button_primary: '#0066ff',
        button_primary_hover: '#0052cc',
        button_text_primary: '#ffffff',
        border_primary: '#e0e0e0'
      },
      dark: {
        bg_primary: '#1a1a1a',
        bg_secondary: '#2d2d2d',
        text_primary: '#ffffff',
        text_secondary: '#a0a0a0',
        button_primary: '#3385ff',
        button_primary_hover: '#4d99ff',
        button_text_primary: '#ffffff',
        border_primary: '#404040'
      }
    }
  },
  return_url: 'https://yoursite.com/return'
});

您无需指定所有颜色属性。未指定的属性将使用默认主题值。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Preview Checkout

Payment Methods

Integration Guide

Adaptive Currency

Adaptive Currency

多语言 Checkout

支持的语言

自动税费计算

Business Tax ID 支持

折扣码

Discount Codes

Validate Discount by Code

智能地址收集

选项

最简地址模式

电话号码收集

自定义字段

可用字段类型

示例

Custom Fields Guide

隐私政策与条款接受

产品集合

Product Collections

Checkout Session 配置

Checkout Sessions API

Checkout Integration Guide

主题自定义

Design & Theme Customization

主题配置选项

颜色配置（浅色/深色模式）

示例

Checkout Sessions API

Preview Checkout

Payment Methods

Integration Guide

​Adaptive Currency

Adaptive Currency

​多语言 Checkout

​支持的语言

​自动税费计算

​Business Tax ID 支持

​折扣码

Discount Codes

Validate Discount by Code

​智能地址收集

​选项

​最简地址模式

​电话号码收集

​自定义字段

​可用字段类型

​示例

Custom Fields Guide

​隐私政策与条款接受

​产品集合

Product Collections

​Checkout Session 配置

Checkout Sessions API

Checkout Integration Guide

​主题自定义

Design & Theme Customization

​主题配置选项

​颜色配置（浅色/深色模式）

​示例

Adaptive Currency

多语言 Checkout

支持的语言

自动税费计算

Business Tax ID 支持

折扣码

智能地址收集

选项

最简地址模式

电话号码收集

自定义字段

可用字段类型

示例

隐私政策与条款接受

产品集合

Checkout Session 配置

主题自定义

主题配置选项

颜色配置（浅色/深色模式）

示例