结账功能

优化转化、全球合规的结账，支持多种货币和语言，自动税务计算，折扣码，附加功能和智能地址收集。

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

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

​

自动税费计算

系统会根据客户的账单所在地自动计算税费，确保符合 GST、VAT 和销售税要求。

在适用情况下，税务规则会根据客户所在的国家和地区应用。当客户更改所在国家或更新地址时，税额会自动更新。最终的税费明细会在付款前清晰显示。

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

​

企业税号支持

对于 B2B 交易，结账页面允许客户输入企业税号（例如 VAT 或 GST 编号）。输入后，系统会实时验证税号，并自动应用适用的税收豁免或反向征税规则。

​

折扣码

客户可以使用你在控制面板中创建的折扣码或促销码。折扣会立即验证，并显示更新后的价格。

当产品启用 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

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

​

智能地址收集

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

​

选项

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

​

最简地址模式

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

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

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

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。

​

电话号码收集

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

标志	默认值	行为
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 会拒绝电话号码收集已禁用但电话号码设为必填的会话。

​

自定义字段

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

​

可用字段类型

类型	描述
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 负载（payment.succeeded、subscription.active）以及 API 响应的 custom_field_responses 数组中。每个结账会话最多可以定义 5 个自定义字段。

Custom Fields Guide

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

​

隐私政策和条款接受

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

• 结账页面会清晰显示 隐私政策 和 买方条款 链接
• 客户必须在完成付款前明确确认这些条款

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

​

产品集合

产品集合提供统一的结账体验，让客户可以在一次结账中查看并选择多个相关产品（例如 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 数组。无法在创建会话时预先应用折扣码。

Product Collections

创建和管理产品集合。

​

结账会话配置

使用 Checkout Sessions API 控制结账行为：

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  customer: {
    email: '[e-mail]',
    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，并自动附加查询参数——包括 payment_id 或 subscription_id、status、email，以及 license_key（如适用）。完整列表请参阅 Checkout Sessions 指南。

Checkout Sessions API

结账会话的完整 API 参考。

Checkout Integration Guide

集成结账的分步指南。

​

主题自定义

使用 customization.theme_config 参数自定义结账页面外观，使其与品牌保持一致。你可以为浅色和深色模式配置颜色、字体、边框圆角和按钮文本。

本节介绍服务器端 API，该 API 使用诸如 bg_primary 之类的属性名称。在会话上设置的主题适用于托管式、叠加式和内嵌式结账。Checkout SDK 的客户端 themeConfig 选项使用诸如 bgPrimary 之类的属性名称，目前已弃用。请参阅 Overlay Checkout。

Design & Theme Customization

从控制面板以可视化方式配置主题，使用预构建主题、字体排版、颜色和实时预览。

​

主题配置选项

属性	描述
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	付款按钮的自定义文本（例如“完成购买”“立即订阅”）

​

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

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

属性	描述
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'
});

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