Checkout Sessions

Quick Start Guide

Get your first checkout session running in under 5 minutes

API Reference & Live Testing

Explore the full API documentation and interactively test Checkout Session requests and responses.

Preview Checkout

Calculate pricing, taxes, and totals before creating a session.

Session Validity: Checkout sessions are valid for 24 hours by default. If you pass confirm=true in your request, the session will only be valid for 15 minutes.

一次性链接：API 返回的 checkout_url 不可重复使用，并会在 24 小时内过期（当 confirm=true 时为 15 分钟）。该链接 предназначен for a single customer to complete one payment. 请为每位客户和每次支付尝试生成新的 checkout session，而不是共享或重复使用链接。

前置条件

Dodo Payments Account

你需要拥有一个已启用且可访问 API 的 Dodo Payments 商户账户。

API Credentials

从 Dodo Payments 控制面板生成 API 凭证：

Products Setup

在实现 checkout session 之前，请先在 Dodo Payments 控制面板中创建产品。

创建第一个 Checkout Session

Node.js SDK
Python SDK
REST API

import DodoPayments from 'dodopayments';

// Initialize the Dodo Payments client
const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function createCheckoutSession() {
  try {
    const session = await client.checkoutSessions.create({
      // Products to sell - use IDs from your Dodo Payments dashboard
      product_cart: [
        {
          product_id: 'prod_123', // Replace with your actual product ID
          quantity: 1
        }
      ],
      
      // Pre-fill customer information to reduce friction
      customer: {
        email: 'customer@example.com',
        name: 'John Doe',
        phone_number: '+1234567890'
      },
      
      // Billing address for tax calculation and compliance
      billing_address: {
        street: '123 Main St',
        city: 'San Francisco',
        state: 'CA',
        country: 'US', // Required: ISO 3166-1 alpha-2 country code
        zipcode: '94102'
      },
      
      // Where to redirect after successful payment
      return_url: 'https://yoursite.com/checkout/success',
      
      // Custom data for your internal tracking
      metadata: {
        order_id: 'order_123',
        source: 'web_app'
      }
    });

    // Redirect your customer to this URL to complete payment
    console.log('Checkout URL:', session.checkout_url);
    console.log('Session ID:', session.session_id);
    
    return session;
    
  } catch (error) {
    console.error('Failed to create checkout session:', error);
    throw error;
  }
}

// Example usage in an Express.js route
app.post('/create-checkout', async (req, res) => {
  try {
    const session = await createCheckoutSession();
    res.json({ checkout_url: session.checkout_url });
  } catch (error) {
    res.status(500).json({ error: 'Failed to create checkout session' });
  }
});

import os
from dodopayments import DodoPayments

# Initialize the Dodo Payments client
client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),  # This is the default and can be omitted
    environment="test_mode",  # defaults to "live_mode"
)

def create_checkout_session():
    """
    Create a checkout session for a single product with customer data pre-filled.
    Returns the session object containing checkout_url for customer redirection.
    """
    try:
        session = client.checkout_sessions.create(
            # Products to sell - use IDs from your Dodo Payments dashboard
            product_cart=[
                {
                    "product_id": "prod_123",  # Replace with your actual product ID
                    "quantity": 1
                }
            ],
            
            # Pre-fill customer information to reduce checkout friction
            customer={
                "email": "customer@example.com",
                "name": "John Doe",
                "phone_number": "+1234567890"
            },
            
            # Billing address for tax calculation and compliance
            billing_address={
                "street": "123 Main St",
                "city": "San Francisco", 
                "state": "CA",
                "country": "US",  # Required: ISO 3166-1 alpha-2 country code
                "zipcode": "94102"
            },
            
            # Where to redirect after successful payment
            return_url="https://yoursite.com/checkout/success",
            
            # Custom data for your internal tracking
            metadata={
                "order_id": "order_123",
                "source": "web_app"
            }
        )
        
        # Redirect your customer to this URL to complete payment
        print(f"Checkout URL: {session.checkout_url}")
        print(f"Session ID: {session.session_id}")
        
        return session
        
    except Exception as error:
        print(f"Failed to create checkout session: {error}")
        raise error

# Example usage in a Flask route
from flask import Flask, jsonify, request

app = Flask(__name__)

@app.route('/create-checkout', methods=['POST'])
def create_checkout():
    try:
        session = create_checkout_session()
        return jsonify({"checkout_url": session.checkout_url})
    except Exception as error:
        return jsonify({"error": "Failed to create checkout session"}), 500

// Direct API call using fetch - useful for any JavaScript environment
async function createCheckoutSession() {
  try {
    const response = await fetch('https://test.dodopayments.com/checkouts', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`
      },
      body: JSON.stringify({
        // Products to sell - use IDs from your Dodo Payments dashboard
        product_cart: [
          {
            product_id: 'prod_123', // Replace with your actual product ID
            quantity: 1
          }
        ],
        
        // Pre-fill customer information to reduce checkout friction
        customer: {
          email: 'customer@example.com',
          name: 'John Doe',
          phone_number: '+1234567890'
        },
        
        // Billing address for tax calculation and compliance
        billing_address: {
          street: '123 Main St',
          city: 'San Francisco',
          state: 'CA', 
          country: 'US', // Required: ISO 3166-1 alpha-2 country code
          zipcode: '94102'
        },
        
        // Where to redirect after successful payment
        return_url: 'https://yoursite.com/checkout/success',
        
        // Custom data for your internal tracking
        metadata: {
          order_id: 'order_123',
          source: 'web_app'
        }
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const session = await response.json();
    
    // Redirect your customer to this URL to complete payment
    console.log('Checkout URL:', session.checkout_url);
    console.log('Session ID:', session.session_id);
    
    return session;
    
  } catch (error) {
    console.error('Failed to create checkout session:', error);
    throw error;
  }
}

// Example: Redirect user to checkout
createCheckoutSession().then(session => {
  window.location.href = session.checkout_url;
});

API 响应

以上所有方法均返回相同的响应结构：

{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}

生成的 checkout_url 只能使用一次，并会在 24 小时内过期。请勿缓存或在不同客户或支付尝试之间重复使用它——需要新链接时，请创建新的 checkout session。

Get the checkout URL

从 API 响应中提取 checkout_url。

Redirect your customer

将客户引导至 checkout URL 以完成购买。

// Redirect immediately
window.location.href = session.checkout_url;

// Or open in new window
window.open(session.checkout_url, '_blank');

替代集成选项：除了重定向之外，你还可以使用 Overlay Checkout（模态覆盖层）或 Inline Checkout（完全嵌入）将 checkout 直接嵌入页面。在原生移动应用中，将相同的 URL 传递给适用于 Android、iOS、React Native 或 Flutter 的 Mobile Checkout SDKs。这些方式均使用相同的 checkout session URL。

Handle the return

支付完成后，客户会被重定向到你的 return_url，并附带包含支付/订阅 ID、状态、客户邮箱以及任何许可证密钥的查询参数。完整列表请参阅 return_url 参数文档。

Request Body

Required Fields

每个 checkout session 所需的必填字段

Optional Fields

用于自定义 checkout 体验的其他配置

必填字段

array

必填

要包含在 checkout session 中的产品数组。每个产品都必须具有来自 Dodo Payments 控制面板的有效 product_id。

混合结账：你可以在同一个 checkout session 中组合一次性支付产品和订阅产品。这支持多种强大场景，例如订阅的设置费、硬件与 SaaS 的捆绑等。

显示 Product Cart Item Properties

string

必填

Dodo Payments 控制面板中产品的唯一标识符。示例： "prod_123abc456def"

integer

必填

产品数量。**示例：**单件使用 1，多件使用 3

array

要附加到产品的 addon 数组。仅当产品为订阅产品时有效。

显示 Addon item properties

string

必填

integer

必填

integer

启用 pay_what_you_want 时客户支付的金额。禁用时将忽略此字段。格式：以货币的最小单位表示（例如 USD 的美分）。例如，要收取 $1.00，请传入 100。

array

针对已附加到此产品的 credit entitlements 的 checkout-session 级覆盖配置。使用此字段可为当前 session 授予不同数量的 credits，例如授予 1,000 个 API credits 而不是产品默认的 500 个，而无需创建单独的产品。

每个 credit_entitlement_id 都必须已附加到该产品。此字段仅覆盖 session 完成时授予的 credits_amount；产品级 credit entitlement 设置（过期、结转等）仍然适用。

显示 Credit entitlement override properties

string

必填

要覆盖的 credit entitlement ID。必须已附加到该产品。

string

必填

为此 checkout session 授予的 credits 数量，覆盖产品级 credits_amount。必须大于零。

查找产品 ID：你可以在 Dodo Payments 控制面板的 Products → View Details 中找到产品 ID，也可以使用 List Products API。

可选字段

配置这些字段以自定义 checkout 体验，并为支付流程添加业务逻辑。

Customer Information

object

客户信息。你可以使用客户 ID 关联现有客户，也可以在 checkout 期间创建新的客户记录。

Attach Existing Customer
New Customer

使用客户 ID 将现有客户关联到 checkout session。

显示 Existing Customer Properties

string

必填

现有客户的唯一标识符。使用此字段可将 checkout session 关联到现有客户，而不是创建新客户。

在 checkout 期间创建新的客户记录。

显示 New Customer Properties

string

必填

客户的电子邮件地址。创建新客户时必填。

string

客户在收据和发票上显示的全名。示例："John Doe" 或 "Jane Smith"

string

客户的国际格式电话号码。某些支付方式和防欺诈验证要求提供此信息。格式：包括国家代码，例如美国号码使用 "+1234567890"

object

用于准确计算税费、防欺诈和满足监管要求的账单地址信息。

当 confirm 设置为 true 时，所有账单地址字段都将成为成功创建 session 的必填项。

显示 Billing address object properties

string

完整的街道地址，包括门牌号、街道名称，以及适用时的公寓/单元号。示例："123 Main St, Apt 4B" 或 "456 Oak Avenue"

string

城市或市镇名称。示例："San Francisco"、"New York"、"London"

string

州、省或地区名称。使用完整名称或标准缩写。示例："California" 或 "CA"、"Ontario" 或 "ON"

string

必填

两位字母的 ISO 国家代码（ISO 3166-1 alpha-2）。提供 billing_address 时，此字段始终为必填项。示例："US"（美国）、"CA"（加拿大）、"GB"（英国）、"DE"（德国）

Country Code Reference

查看受支持国家及其 ISO 代码的完整列表

string

根据国家要求填写邮政编码、ZIP code 或等效信息。示例："94102"（美国）、"M5V 3A8"（加拿大）、"SW1A 1AA"（英国）

Payment Configuration

array

控制 checkout 期间客户可用的支付方式。此功能有助于针对特定市场或业务要求进行优化。可用选项：credit、debit、upi_collect、apple_pay、google_pay、amazon_pay、klarna、affirm、afterpay_clearpay、cashapp、multibanco、bancontact_card、eps、ideal、przelewy24、paypal

重要：始终将 credit 和 debit 作为备用选项，以避免首选支付方式不可用时 checkout 失败。

示例：

["apple_pay", "google_pay", "credit", "debit"]

string

使用固定账单货币覆盖默认的货币选择。使用 ISO 4217 货币代码。支持的货币：USD、EUR、GBP、CAD、AUD、INR 等示例："USD" 表示美元，"EUR" 表示欧元

只有启用 adaptive pricing 时，此字段才会生效。如果禁用 adaptive pricing，将使用产品的默认货币。

boolean

默认值:"false"

为回访客户显示之前保存的支付方式，从而提升 checkout 速度和用户体验。

Session Management

string

支付完成后用于重定向客户的 URL。重定向时，Dodo Payments 会向你的 URL 追加以下查询参数：

参数	类型	条件
`payment_id`	`string`	一次性支付始终存在
`subscription_id`	`string`	订阅支付始终存在
`status`	`string`	始终存在
`license_key`	`string`	产品启用了许可证密钥时存在。多个密钥以逗号分隔
`email`	`string`	客户有记录邮箱时存在

重定向 URL 示例：

# One-time payment with license key
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com

# Subscription payment with multiple license keys
https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001,LK-002&email=customer%40example.com

# Payment without license keys
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&email=customer%40example.com

使用 license_key 和 email 查询参数，在返回页面上显示许可证密钥或立即发送确认，而无需额外的 API 调用。

string

客户点击返回按钮或取消 checkout session 时用于重定向客户的 URL。如果未提供，则不会显示返回按钮。

设置 cancel_url，为客户提供无需完成购买即可返回网站的明确方式。这可以改善 checkout 体验并减少阻碍。

boolean

默认值:"false"

如果为 true，则立即完成所有 session 详细信息。如果缺少必填数据，API 将抛出错误。

array

向 checkout session 应用一个或多个叠加的折扣代码。代码按数组顺序应用（第一个代码降低基础价格，第二个代码降低已折扣的价格，依此类推），每个 session 最多可使用 20 个代码。

discount_codes: ['WELCOME10', 'BLACKFRIDAY20']

下面的单数 discount_code 字段已弃用，但仍受到完整支持——现有集成无需更改即可继续运行。它不能与同一请求中的 discount_codes 组合使用。方便时请迁移到 discount_codes，以使用叠加折扣功能。

string

已弃用

已弃用——新集成请优先使用 discount_codes。为保持向后兼容，此字段仍然有效，但不能与同一请求中的 discount_codes 组合使用。

object

用于存储有关 session 的其他信息的自定义键值对。

boolean

覆盖此 session 的商户默认 3DS 行为。

boolean

默认值:"false"

启用最小地址收集模式。启用后，checkout 仅收集：

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

通过消除不必要的表单字段，此功能可以显著减少 checkout 阻碍。

启用最小地址收集，以更快完成 checkout。对于需要完整账单详细信息的企业，仍可使用完整地址收集。

UI Customization & Features

object

自定义 checkout 界面的外观和行为。

显示 Customization object properties

string

默认值:"system"

checkout 界面的主题。选项：light、dark 或 system。

boolean

默认值:"true"

在 checkout 界面中显示订单详情部分。

boolean

默认值:"true"

为适用的产品显示“按需”标签。

string

强制 checkout 界面以指定语言渲染。默认情况下，checkout 会自动检测客户的浏览器语言。支持的语言代码： ar（阿拉伯语）、ca（加泰罗尼亚语）、de（德语）、en（英语）、es（西班牙语）、fr（法语）、he（希伯来语）、id（印度尼西亚语）、it（意大利语）、ja（日语）、ko（韩语）、ms（马来语）、nl（荷兰语）、pl（波兰语）、pt（葡萄牙语）、ro（罗马尼亚语）、ru（俄语）、sv（瑞典语）、th（泰语）、tr（土耳其语）、zh（中文）示例："es" 表示西班牙语，"ja" 表示日语

object

配置 checkout session 的具体功能和行为。

显示 Feature flags object properties

boolean

默认值:"true"

允许客户在 checkout 期间选择首选货币。

boolean

默认值:"true"

在 checkout 界面中显示折扣代码输入字段。

boolean

默认值:"false"

允许客户在 checkout 期间为订阅产品添加或移除 addons。仅适用于订阅产品。

boolean

默认值:"true"

在 checkout 期间收集客户电话号码。

boolean

默认值:"true"

允许客户输入税务识别号。

boolean

默认值:"false"

强制创建新的客户记录，而不是更新现有记录。

boolean

允许客户在 checkout 期间编辑电子邮件地址。

boolean

允许客户在 checkout 期间编辑姓名。

boolean

允许客户在 checkout 期间编辑街道地址。

boolean

允许客户在 checkout 期间编辑城市。

boolean

允许客户在 checkout 期间编辑州/省/地区。

boolean

允许客户在 checkout 期间编辑国家/地区。

boolean

允许客户在 checkout 期间编辑邮政编码。

boolean

默认值:"false"

跳过默认的支付成功页面，并在支付完成后立即将客户重定向到你的 return_url。

当你有能够提供更佳用户体验的自定义成功页面，或用于移动应用和嵌入式 checkout 流程时，可以使用此选项。

Custom Fields

array

使用自定义表单字段在 checkout 期间收集客户的其他信息。每个 checkout session 最多可定义 5 个自定义字段。客户响应会包含在 webhook payload 中，并可通过 API 获取。

显示 Custom field object properties

string

必填

此字段的唯一标识符。用作 webhook payload 和 API 响应中的键。示例："company_name"、"referral_source"、"team_size"

string

必填

在 checkout 表单中向客户显示的标签。示例："Company Name"、"How did you hear about us?"、"Team Size"

string

必填

用于确定输入验证规则的字段类型。可用类型：

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

boolean

默认值:"false"

此字段是否必须填写才能完成 checkout。

string

输入字段中显示的占位文本。

array

dropdown 字段类型的选项列表。当 field_type 为 dropdown 时必填，其他类型会忽略此字段。示例：["Google", "Twitter", "Friend referral", "Other"]

客户对自定义字段的响应会包含在：

Webhooks：payment.succeeded、subscription.active 以及其他相关事件 payload 中包含 custom_field_responses 数组
API 响应：支付和订阅对象包含 custom_field_responses

Subscription Configuration

object

包含订阅产品的 checkout session 的其他配置。

显示 Subscription data object properties

integer

首次扣款前试用期的天数。必须介于 0 到 10000 天之间。每个 session 不能设置付费试用金额——请改为在产品的 recurring price 上配置 trial_amount。请参阅 Paid Trials。

object

用于基于用量或计量计费的按需订阅配置。

显示 On-demand object properties

boolean

必填

如果设置为 true，则不会执行任何扣款，只会授权支付方式详细信息以供将来使用。

integer

向客户收取的首次扣款的产品价格。如果未指定，将使用产品的存储价格。格式：以货币的最小单位表示（例如 USD 的美分）。例如，要收取 $1.00，请传入 100。

string

产品价格的可选货币。如果未指定，则默认为产品的货币。

string

用于账单和订单项的可选产品描述覆盖。如果未指定，将使用产品的存储描述。

boolean

adaptive currency 费用是否包含在产品价格中（true），或在价格之外另行添加（false）。未启用 adaptive pricing 时会忽略此字段。

使用示例

以下是 10 个全面示例，展示适用于不同业务场景的 checkout session 配置：

1. 简单的单产品 Checkout

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_ebook_guide',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  },
  return_url: 'https://yoursite.com/success'
});

2. 多产品购物车

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_laptop',
      quantity: 1
    },
    {
      product_id: 'prod_mouse',
      quantity: 2
    },
    {
      product_id: 'prod_warranty',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe',
    phone_number: '+1234567890'
  },
  billing_address: {
    street: '123 Tech Street',
    city: 'San Francisco',
    state: 'CA',
    country: 'US',
    zipcode: '94102'
  },
  return_url: 'https://electronics-store.com/order-confirmation'
});

3. 带试用期的订阅

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_plan',
      quantity: 1
    }
  ],
  subscription_data: {
    trial_period_days: 14
  },
  customer: {
    email: 'user@startup.com',
    name: 'Jane Smith'
  },
  return_url: 'https://saas-app.com/onboarding',
  metadata: {
    plan_type: 'professional',
    referral_source: 'google_ads'
  }
});

4. 预确认 Checkout

当 confirm 设置为 true 时，客户将直接进入 checkout 页面，跳过所有确认步骤。

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_premium_course',
      quantity: 1
    }
  ],
  customer: {
    email: 'student@university.edu',
    name: 'Alex Johnson',
    phone_number: '+1555123456'
  },
  billing_address: {
    street: '456 University Ave',
    city: 'Boston',
    state: 'MA',
    country: 'US',
    zipcode: '02134'
  },
  confirm: true,
  return_url: 'https://learning-platform.com/course-access',
  metadata: {
    course_category: 'programming',
    enrollment_date: '2024-01-15'
  }
});

5. 带货币覆盖的 Checkout

只有在账户设置中启用 adaptive currency 时，billing_currency 覆盖才会生效。如果禁用 adaptive currency，此参数不会产生任何影响。

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_consulting_service',
      quantity: 1
    }
  ],
  customer: {
    email: 'client@company.co.uk',
    name: 'Oliver Williams'
  },
  billing_address: {
    street: '789 Business Park',
    city: 'London',
    state: 'England',
    country: 'GB',
    zipcode: 'SW1A 1AA'
  },
  billing_currency: 'GBP',
  feature_flags: {
    allow_currency_selection: true,
    allow_tax_id: true
  },
  return_url: 'https://consulting-firm.com/service-confirmation'
});

6. 为回访客户保存支付方式

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_subscription',
      quantity: 1
    }
  ],
  customer: {
    email: 'returning.customer@example.com',
    name: 'Robert Johnson',
    phone_number: '+1555987654'
  },
  show_saved_payment_methods: true,
  feature_flags: {
    allow_phone_number_collection: true,
    always_create_new_customer: false
  },
  return_url: 'https://subscription-service.com/welcome-back',
  metadata: {
    customer_tier: 'premium',
    account_age: 'returning'
  }
});

7. 收集税务 ID 的 B2B Checkout

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_enterprise_license',
      quantity: 5
    }
  ],
  customer: {
    email: 'procurement@enterprise.com',
    name: 'Sarah Davis',
    phone_number: '+1800555000'
  },
  billing_address: {
    street: '1000 Corporate Blvd',
    city: 'New York',
    state: 'NY',
    country: 'US',
    zipcode: '10001'
  },
  feature_flags: {
    allow_tax_id: true,
    allow_phone_number_collection: true,
    always_create_new_customer: false
  },
  return_url: 'https://enterprise-software.com/license-delivery',
  metadata: {
    customer_type: 'enterprise',
    contract_id: 'ENT-2024-001',
    sales_rep: 'john.sales@company.com'
  }
});

8. 带叠加折扣代码的深色主题 Checkout

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_gaming_chair',
      quantity: 1
    }
  ],
  discount_codes: ['BLACKFRIDAY2024'],
  customization: {
    theme: 'dark',
    show_order_details: true,
    show_on_demand_tag: false
  },
  feature_flags: {
    allow_discount_code: true
  },
  customer: {
    email: 'gamer@example.com',
    name: 'Mike Chen'
  },
  return_url: 'https://gaming-store.com/order-complete'
});

9. 区域性支付方式（印度 UPI）

有关 UPI 配置和测试的详细信息，请参阅 India Payment Methods 页面。

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_online_course_hindi',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'upi_collect',
    'credit',
    'debit'
  ],
  customer: {
    email: 'student@example.in',
    name: 'Priya Sharma',
    phone_number: '+919876543210'
  },
  billing_address: {
    street: 'MG Road',
    city: 'Bangalore',
    state: 'Karnataka',
    country: 'IN',
    zipcode: '560001'
  },
  billing_currency: 'INR',
  return_url: 'https://education-platform.in/course-access',
  metadata: {
    region: 'south_india',
    language: 'hindi'
  }
});

10. BNPL（先买后付）Checkout

有关 BNPL 配置和测试的详细信息，请参阅 Buy Now Pay Later (BNPL) 页面。

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_luxury_watch',
      quantity: 1
    }
  ],
  allowed_payment_method_types: [
    'klarna',
    'afterpay_clearpay',
    'credit',
    'debit'
  ],
  customer: {
    email: 'fashion.lover@example.com',
    name: 'Emma Thompson',
    phone_number: '+1234567890'
  },
  billing_address: {
    street: '555 Fashion Ave',
    city: 'Los Angeles',
    state: 'CA',
    country: 'US',
    zipcode: '90210'
  },
  feature_flags: {
    allow_phone_number_collection: true
  },
  return_url: 'https://luxury-store.com/purchase-confirmation',
  metadata: {
    product_category: 'luxury',
    price_range: 'high_value'
  }
});

11. 使用现有支付方式进行即时 Checkout

使用客户已保存的支付方式创建能够立即处理的 checkout session，并跳过支付方式收集：

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_premium_plan',
      quantity: 1
    }
  ],
  customer: {
    customer_id: 'cus_123'  // Required when using payment_method_id
  },
  payment_method_id: 'pm_abc123',  // Use customer's saved payment method
  confirm: true,  // Required when using payment_method_id
  return_url: 'https://yourapp.com/success'
});

使用 payment_method_id 时，必须将 confirm 设置为 true，并提供现有的 customer_id。系统会根据支付货币验证该支付方式是否符合条件。

支付方式必须属于该客户，并且必须与支付货币兼容。这可以为回访客户实现一键购买。

12. 用于生成简洁支付 URL 的短链接

使用自定义 slug 生成可缩短且可分享的支付链接：

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_subscription',
      quantity: 1
    }
  ],
  short_link: true,  // Generate a shortened payment link
  return_url: 'https://yourapp.com/success',
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  }
});

// The checkout_url will be a shortened, cleaner link
console.log(session.checkout_url);  // e.g., https://checkout.dodopayments.com/buy/abc123

短链接非常适合通过 SMS、电子邮件或社交媒体分享。相比长 URL，它们更容易记忆，也更能建立客户信任。

13. 跳过支付成功页面并立即重定向

在支付完成后立即重定向客户，跳过默认的成功页面：

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_digital_product',
      quantity: 1
    }
  ],
  feature_flags: {
    redirect_immediately: true  // Skip success page, redirect immediately
  },
  return_url: 'https://yourapp.com/success',
  customer: {
    email: 'customer@example.com',
    name: 'Jane Smith'
  }
});

当你有比默认支付成功页面提供更佳用户体验的自定义成功页面时，请使用 redirect_immediately: true。这对于移动应用和嵌入式 checkout 流程尤其有用。

启用 redirect_immediately 后，客户会在支付完成后立即被重定向到你的 return_url，完全跳过默认的成功页面。

14. 强制指定语言

强制 checkout 以指定语言显示，覆盖客户浏览器的语言检测结果：

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_subscription',
      quantity: 1
    }
  ],
  customization: {
    force_language: 'ja'  // Force Japanese language
  },
  customer: {
    email: 'customer@example.jp',
    name: 'Tanaka Yuki'
  },
  return_url: 'https://yourapp.com/success'
});

当你知道客户的首选语言（例如来自其账户设置），或要面向特定区域市场时，请使用 force_language。

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

15. 收集自定义字段

使用自定义字段在 checkout 期间收集客户的其他信息：

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_saas_plan',
      quantity: 1
    }
  ],
  custom_fields: [
    {
      key: 'company_name',
      label: 'Company Name',
      field_type: 'text',
      required: true,
      placeholder: 'Acme Inc.'
    },
    {
      key: 'team_size',
      label: 'Team Size',
      field_type: 'dropdown',
      required: true,
      options: ['1-10', '11-50', '51-200', '201-500', '500+']
    },
    {
      key: 'referral_source',
      label: 'How did you hear about us?',
      field_type: 'dropdown',
      required: false,
      options: ['Google', 'Twitter', 'Friend referral', 'Blog post', 'Other']
    },
    {
      key: 'website',
      label: 'Company Website',
      field_type: 'url',
      required: false,
      placeholder: 'https://example.com'
    }
  ],
  customer: {
    email: 'buyer@company.com',
    name: 'Jane Doe'
  },
  return_url: 'https://yourapp.com/success'
});

自定义字段响应会自动包含在 webhook payload 中（payment.succeeded、subscription.active 等），并可通过 API 获取。你可以使用这些信息丰富 CRM、触发 onboarding 流程或自定义客户体验。

可用字段类型： text、number、email、url、date、dropdown、boolean

预览 Checkout Sessions

创建 checkout session 之前，你可以预览包含税费、折扣和总额的价格明细。这有助于在客户进入 checkout 之前显示准确的价格。

当购物车包含订阅产品时，预览响应还会返回 next_billing_date——即即将到来的账单日期预览，以便你在创建订阅之前将其显示给客户。它相对于当前时间计算：适用试用期时为 now + trial period，否则为 now + one payment frequency。一次性购物车不会包含此字段。这是基于预览时间的估算；权威的 next_billing_date 会在订阅激活时设置。

预览还会返回 trial_period_days（有效试用期长度，免费或付费）和 trial_amount（折扣后的每单位试用费用，以价格货币的最小单位表示）。trial_amount 仅在付费试用时存在；免费试用或无试用时为 null。使用 current_breakup 获取今天实际应付的含税总额。

Node.js SDK
Python SDK

const preview = await client.checkoutSessions.preview({
  product_cart: [
    { product_id: 'prod_123', quantity: 1 }
  ],
  billing_address: {
    country: 'US',
    state: 'CA',
    zipcode: '94102'
  },
  discount_codes: ['SAVE20']
});

console.log('Subtotal:', preview.subtotal);
console.log('Tax:', preview.tax);
console.log('Discount:', preview.discount);
console.log('Total:', preview.total);

// Present only when the cart contains a subscription product
console.log('Next billing date:', preview.next_billing_date);

preview = client.checkout_sessions.preview(
    product_cart=[
        {"product_id": "prod_123", "quantity": 1}
    ],
    billing_address={
        "country": "US",
        "state": "CA",
        "zipcode": "94102"
    },
    discount_codes=["SAVE20"]
)

print(f"Subtotal: {preview.subtotal}")
print(f"Tax: {preview.tax}")
print(f"Discount: {preview.discount}")
print(f"Total: {preview.total}")

# Present only when the cart contains a subscription product
print(f"Next billing date: {preview.next_billing_date}")

Preview API Reference

查看完整的预览 endpoint 文档。

从 Dynamic Links 迁移到 Checkout Sessions

主要区别

以前使用 Dynamic Links 创建支付链接时，必须提供客户完整的账单地址。使用 Checkout Sessions 后，不再需要这样做。你只需传递已有的信息，剩余部分由我们处理。例如：

如果你只知道客户的账单国家/地区，只需提供该信息。
checkout 流程会在将客户带到支付页面之前自动收集缺失的信息。
另一方面，如果你已经拥有所有必需信息，并希望直接跳转到支付页面，则可以传递完整数据集，并在请求正文中包含 confirm=true。

迁移流程

从 Dynamic Links 迁移到 Checkout Sessions 非常简单：

Update your integration

更新集成，以使用新的 API 或 SDK 方法。

Adjust request payload

根据 Checkout Sessions 格式调整请求 payload。

That's it!

是。不需要在你的一侧进行额外处理或执行特殊迁移步骤。

Create Checkout Session

创建 checkout session 的完整 API 参考，包含所有可用参数和选项

Preview Checkout Session

在创建 session 之前预览价格、税费和总额的 API 参考

Integration Guides

Billing Deconstructions

Cookbooks

Quick Start Guide

API Reference & Live Testing

Preview Checkout

前置条件

创建第一个 Checkout Session

API 响应

Request Body

Required Fields

Optional Fields

必填字段

可选字段

Country Code Reference

使用示例

1. 简单的单产品 Checkout

2. 多产品购物车

3. 带试用期的订阅

4. 预确认 Checkout

5. 带货币覆盖的 Checkout

6. 为回访客户保存支付方式

7. 收集税务 ID 的 B2B Checkout

8. 带叠加折扣代码的深色主题 Checkout

9. 区域性支付方式（印度 UPI）

10. BNPL（先买后付）Checkout

11. 使用现有支付方式进行即时 Checkout

12. 用于生成简洁支付 URL 的短链接

13. 跳过支付成功页面并立即重定向

14. 强制指定语言

15. 收集自定义字段

预览 Checkout Sessions

Preview API Reference

从 Dynamic Links 迁移到 Checkout Sessions

主要区别

迁移流程

相关 API 参考

Create Checkout Session

Preview Checkout Session

Quick Start Guide

API Reference & Live Testing

Preview Checkout

​前置条件

​创建第一个 Checkout Session

​API 响应

​Request Body

Required Fields

Optional Fields

​必填字段

​可选字段

Country Code Reference

​使用示例

​1. 简单的单产品 Checkout

​2. 多产品购物车

​3. 带试用期的订阅

​4. 预确认 Checkout

​5. 带货币覆盖的 Checkout

​6. 为回访客户保存支付方式

​7. 收集税务 ID 的 B2B Checkout

​8. 带叠加折扣代码的深色主题 Checkout

​9. 区域性支付方式（印度 UPI）

​10. BNPL（先买后付）Checkout

​11. 使用现有支付方式进行即时 Checkout

​12. 用于生成简洁支付 URL 的短链接

​13. 跳过支付成功页面并立即重定向

​14. 强制指定语言

​15. 收集自定义字段

​预览 Checkout Sessions

Preview API Reference

​从 Dynamic Links 迁移到 Checkout Sessions

​主要区别

​迁移流程

​相关 API 参考

Create Checkout Session

Preview Checkout Session

前置条件

创建第一个 Checkout Session

API 响应

Request Body

必填字段

可选字段

使用示例

1. 简单的单产品 Checkout

2. 多产品购物车

3. 带试用期的订阅

4. 预确认 Checkout

5. 带货币覆盖的 Checkout

6. 为回访客户保存支付方式

7. 收集税务 ID 的 B2B Checkout

8. 带叠加折扣代码的深色主题 Checkout

9. 区域性支付方式（印度 UPI）

10. BNPL（先买后付）Checkout

11. 使用现有支付方式进行即时 Checkout

12. 用于生成简洁支付 URL 的短链接

13. 跳过支付成功页面并立即重定向

14. 强制指定语言

15. 收集自定义字段

预览 Checkout Sessions

从 Dynamic Links 迁移到 Checkout Sessions

主要区别

迁移流程

相关 API 参考