结账功能 - Dodo Payments Documentation

Dodo Payments 结账页面是面向数字产品和 SaaS 业务的转化优化、全球合规结账。它支持多种货币、语言、税费、折扣、附加项以及企业友好的合规模式。

Checkout Sessions API

通过编程方式创建托管结账会话。

Preview Checkout

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

Payment Methods

支持的支付方式和配置选项。

自适应货币

自适应货币允许客户以他们首选的本地货币付款，从而提高信任度和转化率。

工作原理

启用: 从 设置 → 业务 中启用自适应货币
选择: 客户可以直接在结账时切换货币
转换: 使用实时外汇汇率动态转换价格
显示: 付款前透明显示最终应付金额

Adaptive Currency

了解更多支持的货币、兑换费用和退款处理。

多语言结账

Dodo Payments 在结账页面支持多种语言，允许客户以他们熟悉的语言完成支付。

主要亮点

结账时直接提供语言选择器
UI 文本、标签和系统消息已本地化
提高可访问性和国际转化率

支持的语言

结账页面支持 21 种语言：

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

您可以在创建结账会话时设置 force_language 参数强制使用特定语言。详情请参见 Checkout Sessions API 。

自动税费计算

税费会根据客户的账单地址自动计算，确保符合 GST、VAT 和销售税要求，无需手动设置。

税费计算原理

Location Detection

税规则根据客户所在国家（及适用地区）应用。

Dynamic Updates

税额会在以下情况下自动更新：

国家更改
地址更新

Transparent Display

最终税费细目在付款前清晰展示。

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

企业税号支持

对于注册企业，结账允许客户输入其企业税号（例如 VAT/GST 号）。

输入税号后发生什么

实时验证税收资格
应用适用的免税或反向收费规则
结账时税额立即更新

这对于 B2B SaaS 和数字服务尤其有用，那里的企业客户可能有资格享受税收减免。

折扣码

客户可以在结账页直接使用您在仪表板中创建的折扣或促销代码。

结账体验

客户输入折扣码
折扣即时验证
清晰展示更新后的价格和节省金额

API 集成

预先应用折扣码或启用折扣输入字段：

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'prod_abc', quantity: 1 }
  ],
  discount_code: 'WELCOME20', // Pre-apply a code
  feature_flags: {
    allow_discount_code: true // Show discount input field
  },
  return_url: 'https://yoursite.com/return'
});

Discount Codes

了解如何创建和管理折扣码。

Validate Discount by Code

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

智能地址收集

结账支持灵活的地址输入，加快完成速度。

可用选项

选项	描述
Google 地址自动填充	带自动完成功能的快速选择
手动输入	可完全控制完整地址
国家选择	驱动税务及合规逻辑

地址收集在速度、准确性和全球覆盖之间取得平衡，最大化转化同时确保合规。

自定义字段

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

可用字段类型

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

示例

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'prod_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）以及通过 custom_field_responses 数组的 API 响应中。您可以为每个结账会话定义最多 5 个自定义字段。

Custom Fields Guide

了解自定义字段配置及获取响应的更多信息。

隐私政策与条款接受

为确保法律与合规透明：

Privacy Policy 和 Buyer Terms 链接会在结账页清晰展示
客户在完成付款前会明确确认这些内容

这有助于满足全球消费者保护和数据隐私要求，包括 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: 'prod_abc', quantity: 1 }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'Jane Doe'
  },
  billing_currency: 'EUR', // Set specific currency
  discount_code: 'PROMO10',
  feature_flags: {
    allow_discount_code: true
  },
  return_url: 'https://yoursite.com/return',
  cancel_url: 'https://yoursite.com/pricing', // Optional: where to redirect on cancel
  metadata: {
    order_ref: 'ORD-12345'
  }
});

付款后，客户会自动重定向到您的 return_url，并自动附加查询参数 —— 包括 payment_id 或 subscription_id、status、email 和 license_key（如适用）。完整列表请参见 Checkout Sessions guide。

Checkout Sessions API

结账会话的完整 API 参考。

Checkout Integration Guide

逐步指南，指导集成结账。

结账主题自定义

在通过 API 创建结账会话时，使用 customization.theme_config 参数自定义结账页面外观以匹配品牌。配置包括亮/暗模式的颜色、字体、边框半径和按钮文本。

Design & Theme Customization

从仪表板以可视方式配置主题，可使用预构建的主题、排版、颜色和实时预览。

本节介绍使用 customization.theme_config 进行的服务器端 API主题配置。如果您正在使用Checkout SDK（覆盖式或内嵌式结账），请参阅 Overlay Checkout 或 Inline Checkout 中的主题自定义部分，这些部分使用 camelCase 属性（例如使用 bgPrimary 而不是 bg_primary）。

主题配置选项

属性	描述
`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`	用户界面元素的边角半径（例如 `4px`、`0.5rem`、`8px`）
`pay_button_text`	支付按钮的自定义文本（例如 “Complete Purchase”、“Subscribe Now”）

颜色配置（亮色/暗色模式）

每个模式（light 和 dark）都支持以下颜色属性：

属性	描述
`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 颜色格式：

十六进制：#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: 'prod_abc', quantity: 1 }
  ],
  customization: {
    theme_config: {
      // Custom fonts
      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 mode colors
      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 mode colors
      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

Documentation Index

Checkout Sessions API

Preview Checkout

Payment Methods

​自适应货币

​工作原理

Adaptive Currency

​多语言结账

​主要亮点

​支持的语言

​自动税费计算

​税费计算原理

​企业税号支持

​输入税号后发生什么

​折扣码

​结账体验

​API 集成

Discount Codes

Validate Discount by Code

​智能地址收集

​可用选项

​自定义字段

​可用字段类型

​示例

Custom Fields Guide

​隐私政策与条款接受

​产品组合结账

​工作原理

​创建产品组合结账

Product Collections

​结账会话配置

Checkout Sessions API

Checkout Integration Guide

​结账主题自定义

Design & Theme Customization

​主题配置选项

​颜色配置（亮色/暗色模式）

​示例

自适应货币

工作原理

多语言结账

主要亮点

支持的语言

自动税费计算

税费计算原理

企业税号支持

输入税号后发生什么

折扣码

结账体验

API 集成

智能地址收集

可用选项

自定义字段

可用字段类型

示例

隐私政策与条款接受

产品组合结账

工作原理

创建产品组合结账

结账会话配置

结账主题自定义

主题配置选项

颜色配置（亮色/暗色模式）

示例