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: 'pdt_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": "pdt_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: 'pdt_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"
}

只有 session_id 可以保证存在。以下两种情况会返回额外字段或字段更少：

已提供 payment_method_id — 该 charge 会立即处理，且 checkout_url 为 null。请改用返回的 payment_id。
confirm: true 在创建 session 时创建了 payment — 响应还会包含 payment_id、client_secret 和 publishable_key，供 Dodo Payments checkout SDK 使用。

生成的 checkout_url 只能使用一次，并会在 24 小时内过期。不要在不同客户或 payment 尝试之间缓存或重复使用它——每当需要新链接时，都应创建新的 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');

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

Handle the return

payment 完成后，客户会被重定向到你的 return_url，并附带查询参数，包括 payment/subscription ID、status、客户 email 以及任何 license keys。完整列表请参阅 return_url parameter docs。

Request Body

Required Fields

每个 checkout session 所需的基本字段

Optional Fields

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

Required Fields

array

必填

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

Mixed Checkout：你可以在同一个 checkout session 中组合一次性 payment 产品和 subscription 产品。这支持多种强大用例，例如 subscription 的设置费、硬件与 SaaS 的组合套餐等。

显示 Product Cart Item Properties

string

必填

Dodo Payments dashboard 中产品的唯一标识符。示例： "pdt_123abc456def"

integer

必填

产品数量。Example: 单件商品使用 1，多件商品使用 3

array

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

显示 Addon item properties

string

必填

integer

必填

integer

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

array

针对已附加到此产品的 credit entitlements，按 checkout session 进行覆盖。使用此字段可仅为当前 session 授予不同数量的 credits——例如，授予 1,000 个 API credits 而非产品默认的 500 个促销套餐——无需创建单独的产品。

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

显示 Credit entitlement override properties

string

必填

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

string

必填

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

Find Your Product IDs：你可以在 Dodo Payments dashboard 的 Products → View Details 中找到产品 ID，也可以使用 List Products API。

Optional Fields

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

Customer Information

object

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

Attach Existing Customer
New Customer

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

显示 Existing Customer Properties

string

必填

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

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

显示 New Customer Properties

string

必填

客户的 email 地址。创建新客户时必填。

string

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

string

客户的国际格式电话号码。某些 payment methods 和 fraud prevention 场景要求提供此字段。Format：包含国家/地区代码，例如美国号码使用 "+1234567890"

object

用于准确计算税费、防止欺诈并满足监管合规要求的 billing address 信息。

当 confirm 设置为 true 时，所有 billing address 字段都必须填写，session 才能成功创建。

显示 Billing address object properties

string

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

string

城市或市镇名称。Example: "San Francisco"、"New York"、"London"

string

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

string

必填

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

Country Code Reference

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

string

根据国家/地区要求填写的邮政编码、ZIP code 或等效值。Examples: "94102"（美国）、"M5V 3A8"（加拿大）、"SW1A 1AA"（英国）

Payment Configuration

array

控制 checkout 期间客户可使用的 payment methods。此字段有助于针对特定市场或业务要求进行优化。常见选项：credit、debit、upi_collect、apple_pay、google_pay、amazon_pay、klarna、affirm、afterpay_clearpay、cashapp、ach、multibanco、bancontact_card、eps、ideal、blik、paypal。这并非完整集合——有关每个可接受值，请参阅 Create Checkout Session API reference。

Critical：始终将 credit 和 debit 作为备用选项，以便在首选 payment methods 不可用时避免 checkout 失败。

Example：

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

string

使用固定的 billing currency 覆盖默认 currency 选择。使用 ISO 4217 currency codes。Supported Currencies：USD、EUR、GBP、CAD、AUD、INR 等Example："USD" 表示美元，"EUR" 表示欧元

此字段仅在 adaptive pricing 启用时生效。如果 adaptive pricing 已禁用，则使用产品的默认 currency。

boolean

默认值:"false"

为回头客显示之前保存的 payment methods，从而提升 checkout 速度和用户体验。

Session Management

string

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

Parameter	Type	Condition
`payment_id`	`string`	一次性 payment 始终存在
`subscription_id`	`string`	subscription payment 始终存在
`status`	`string`	始终存在
`license_key`	`string`	产品启用了 license keys 时存在；存在多个 key 时以逗号分隔
`email`	`string`	客户有已记录的 email 时存在

Example redirect URLs:

# 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 查询参数，可以在返回页面上显示 license keys 或立即发送确认，而无需额外的 API 调用。

string

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

设置 cancel_url，为客户提供一种明确的方式返回你的网站而不完成购买。这可以改善 checkout 体验并减少操作阻力。

boolean

默认值:"false"

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

array

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

discount_codes: ['WELCOME10', 'BLACKFRIDAY20']

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

string

已弃用

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

object

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

boolean

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

boolean

默认值:"false"

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

Country：税费确定始终必填
ZIP/Postal code：仅在销售税、VAT 或 GST 计算需要的地区收集

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

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

string

属于已关联客户的已保存 payment method。需要 confirm: true 和现有的 customer.customer_id。设置后，charge 会立即处理，并将 checkout_url 作为 null 返回——请改用返回的 payment_id。

boolean

默认值:"false"

如果为 true，则返回缩短的 checkout URL，而不是完整的 session URL。

string

基于 collection 的 checkout 流程所使用的产品 collection ID。

string

客户的 Tax ID（例如 VAT number）。需要 billing_address 以及一个 country。

string

与 Tax ID 关联的可选 business 或 legal name。与有效的 tax_id 一起提供时，该名称会显示在 invoice 上，而不是客户的个人姓名。

integer

覆盖 merchant-level mandate floor（以 INR paise 表示），用于印度银行卡上的 INR e-mandates。

UI Customization & Features

object

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

显示 Customization object properties

string

默认值:"system"

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

boolean

默认值:"true"

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

boolean

默认值:"true"

为适用的产品显示“on-demand”标签。

string

强制 checkout 界面以指定语言呈现。默认情况下，checkout 会自动检测客户的浏览器语言。Supported language codes: ar（Arabic）、ca（Catalan）、de（German）、en（English）、es（Spanish）、fr（French）、he（Hebrew）、id（Indonesian）、it（Italian）、ja（Japanese）、ko（Korean）、ms（Malay）、nl（Dutch）、pl（Polish）、pt（Portuguese）、ro（Romanian）、ru（Russian）、sv（Swedish）、th（Thai）、tr（Turkish）、zh（Chinese）Example："es" 表示 Spanish，"ja" 表示 Japanese

object

自定义主题配置，包括浅色和深色模式的颜色、字体及按钮样式。这是已弃用的客户端 themeConfig 选项的服务器端替代方案。

显示 Theme config properties

object

浅色模式的颜色配置。

object

深色模式的颜色配置。

string

主字体的 URL。必须是有效的 https:// URL。

string

辅助字体的 URL。必须是有效的 https:// URL。

string

checkout UI 的字体大小。选项：xs、sm、md、lg、xl、2xl。

string

checkout UI 的字体粗细。选项：normal、medium、bold、extraBold。

string

支付按钮的自定义文本（例如 "Complete Purchase" 或 "Subscribe Now"）。最多 100 个字符。

string

UI 元素的边框圆角。数字后跟 px、rem 或 em（例如 "4px"、"0.5rem"、"1em"）。

object

配置 checkout session 的特定功能和行为。

显示 Feature flags object properties

boolean

默认值:"true"

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

boolean

默认值:"true"

在 checkout 界面显示 discount code 输入字段。

boolean

默认值:"false"

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

boolean

默认值:"true"

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

boolean

默认值:"false"

要求客户提供电话号码才能完成 checkout。还要求 allow_phone_number_collection 为 true。

boolean

默认值:"true"

允许客户输入 Tax identification numbers。

boolean

默认值:"false"

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

boolean

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

boolean

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

boolean

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

boolean

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

boolean

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

boolean

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

boolean

允许客户在 checkout 期间编辑 zipcode。

boolean

允许客户在 checkout 期间输入或编辑 Tax ID。

boolean

默认值:"false"

允许客户提供或编辑与 Tax ID 关联的 business name。独立于 allow_customer_editing_tax_id 工作——任一 flag（或 allow_tax_id）都足够。通常与 allow_customer_editing_tax_id 一起设置。

boolean

默认值:"false"

跳过默认的 payment success page，并在 payment 完成后立即将客户重定向到你的 return_url。

当你拥有可提供更佳用户体验的自定义 success page，或用于移动应用和嵌入式 checkout 流程时，请使用此选项。

Custom Fields

array

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

显示 Custom field object properties

string

必填

此字段的唯一标识符。用作 webhook payload 和 API 响应中的 key。Example: "company_name"、"referral_source"、"team_size"

string

必填

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

string

必填

决定输入验证规则的字段类型。Available types：

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

boolean

默认值:"false"

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

string

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

array

dropdown 字段类型的选项列表。当 field_type 为 dropdown 时必填，对其他类型忽略。Example: ["Google", "Twitter", "Friend referral", "Other"]

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

Webhooks：payment.succeeded、subscription.active 及其他相关 event payload 包含 custom_field_responses 数组
API responses：Payment 和 subscription 对象包含 custom_field_responses

Subscription Configuration

object

包含 subscription 产品的 checkout sessions 的其他配置。

显示 Subscription data object properties

integer

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

object

基于用量或计量计费的 on-demand subscription 配置。

显示 On-demand object properties

boolean

必填

如果设置为 true，则不执行任何 charge，仅授权 payment method 详情以供将来使用。

integer

向客户收取的初始 charge 的产品价格。如果未指定，则使用产品的存储价格。Format：以货币的最小单位表示（例如 USD 的 cents）。例如，要收取 $1.00，请传入 100。

string

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

string

用于 billing 和 line items 的可选产品描述覆盖值。如果未指定，则使用产品的存储描述。

boolean

adaptive currency fees 是否包含在产品价格中（true），或在其上额外收取（false）。如果 adaptive pricing 未启用，则忽略此字段。

Usage Examples

以下 10 个完整示例展示了适用于不同业务场景的 checkout session 配置：

1. Simple Single Product Checkout

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

2. Multi-Product Cart

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_laptop',
      quantity: 1
    },
    {
      product_id: 'pdt_mouse',
      quantity: 2
    },
    {
      product_id: 'pdt_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. Subscription with Trial Period

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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. Pre-confirmed Checkout

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

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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 with Currency Override

仅当账户设置中启用了 adaptive currency 时，billing_currency 覆盖值才会生效。如果 adaptive currency 已禁用，此参数不会产生任何影响。

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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. Saved Payment Methods for Returning Customers

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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. B2B Checkout with Tax ID Collection

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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. Dark Theme Checkout with Stacked Discount Codes

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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. Regional Payment Methods (UPI for India)

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

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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 (Buy Now Pay Later) Checkout

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

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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. Using Existing Payment Methods for Instant Checkout

使用客户已保存的 payment method 创建一个立即处理的 checkout session，跳过 payment method 收集：

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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。系统会根据 payment 的 currency 验证 payment method 是否符合条件。由于 charge 会立即处理，checkout_url 会作为 null 返回——请改用返回的 payment_id。

Payment method 必须属于该客户，并且与 payment currency 兼容。这使回头客能够一键购买。

12. Short Links for Cleaner Payment URLs

使用自定义 slugs 生成更短且可分享的 payment links：

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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

Short links 非常适合通过 SMS、email 或社交媒体分享。它们比长 URL 更容易记忆，也能建立更多客户信任。

13. Skip Payment Success Page with Immediate Redirect

在 payment 完成后立即重定向客户，跳过默认 success page：

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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'
  }
});

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

启用 redirect_immediately 后，客户会在 payment 完成后立即被重定向到你的 return_url，完全跳过默认 success page。

14. Forcing a Language

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

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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。

Supported languages: Arabic (ar)、Catalan (ca)、Chinese (zh)、Dutch (nl)、English (en)、French (fr)、German (de)、Hebrew (he)、Indonesian (id)、Italian (it)、Japanese (ja)、Korean (ko)、Malay (ms)、Polish (pl)、Portuguese (pt)、Romanian (ro)、Russian (ru)、Spanish (es)、Swedish (sv)、Thai (th)、Turkish (tr)

15. Collecting Custom Fields

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

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_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 流程或自定义客户体验。

Available field types: text、number、email、url、date、dropdown、boolean

Previewing Checkout Sessions

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

当购物车包含 subscription 产品时，preview response 还会返回 next_billing_date——即 upcoming billing date 的预览，以便你在创建 subscription 前显示该日期。它相对于当前时间计算：适用 trial 时为 now + trial period，否则为 now + one payment frequency。仅包含一次性产品的购物车不会返回此字段。这是基于 preview 时间的估算；权威的 next_billing_date 会在 subscription 激活时设置。

preview 还会返回 trial_period_days（实际 trial 时长，可为免费或付费）和 trial_amount（折扣后的每单位 trial charge，以价格 currency 的最小单位表示）。trial_amount 仅在付费 trial时存在；免费 trial 或无 trial 时为 null。使用 current_breakup 获取今天实际应付的含税总额。

Node.js SDK
Python SDK

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

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

// 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": "pdt_123", "quantity": 1}
    ],
    billing_address={
        "country": "US",
        "state": "CA",
        "zipcode": "94102"
    },
    discount_codes=["SAVE20"]
)

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

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

Preview API Reference

查看完整的 preview endpoint 文档。

Moving from Dynamic Links to Checkout Sessions

Key Differences

以前使用 Dynamic Links 创建 payment link 时，必须提供客户完整的 billing address。使用 Checkout Sessions 后，这不再是必需的。你只需传递已有的信息，其余部分由我们处理。例如：

如果只知道客户的 billing country，只需提供该信息。
checkout flow 会在将客户转到 payment page 前自动收集缺失的详情。
另一方面，如果你已经拥有所有必需信息，并希望直接跳转到 payment page，则可以传递完整数据集，并在 request body 中包含 confirm=true。

Migration Process

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

Update your integration

更新 integration，以使用新的 API 或 SDK method。

Adjust request payload

根据 Checkout Sessions 格式调整 request payload。

That's it!

是。不需要在你这边进行额外处理或特殊迁移步骤。

Create Checkout Session

使用所有可用参数和选项创建 checkout sessions 的完整 API reference

Preview Checkout Session

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

Integration Guides

Billing Deconstructions

Cookbooks

Quick Start Guide

API Reference & Live Testing

Preview Checkout

前置条件

创建第一个 Checkout Session

API 响应

Request Body

Required Fields

Optional Fields

Required Fields

Optional Fields

Country Code Reference

Usage Examples

1. Simple Single Product Checkout

2. Multi-Product Cart

3. Subscription with Trial Period

4. Pre-confirmed Checkout

5. Checkout with Currency Override

6. Saved Payment Methods for Returning Customers

7. B2B Checkout with Tax ID Collection

8. Dark Theme Checkout with Stacked Discount Codes

9. Regional Payment Methods (UPI for India)

10. BNPL (Buy Now Pay Later) Checkout

11. Using Existing Payment Methods for Instant Checkout

12. Short Links for Cleaner Payment URLs

13. Skip Payment Success Page with Immediate Redirect

14. Forcing a Language

15. Collecting Custom Fields

Previewing Checkout Sessions

Preview API Reference

Moving from Dynamic Links to Checkout Sessions

Key Differences

Migration Process

Create Checkout Session

Preview Checkout Session

Quick Start Guide

API Reference & Live Testing

Preview Checkout

​前置条件

​创建第一个 Checkout Session

​API 响应

​Request Body

Required Fields

Optional Fields

​Required Fields

​Optional Fields

Country Code Reference

​Usage Examples

​1. Simple Single Product Checkout

​2. Multi-Product Cart

​3. Subscription with Trial Period

​4. Pre-confirmed Checkout

​5. Checkout with Currency Override

​6. Saved Payment Methods for Returning Customers

​7. B2B Checkout with Tax ID Collection

​8. Dark Theme Checkout with Stacked Discount Codes

​9. Regional Payment Methods (UPI for India)

​10. BNPL (Buy Now Pay Later) Checkout

​11. Using Existing Payment Methods for Instant Checkout

​12. Short Links for Cleaner Payment URLs

​13. Skip Payment Success Page with Immediate Redirect

​14. Forcing a Language

​15. Collecting Custom Fields

​Previewing Checkout Sessions

Preview API Reference

​Moving from Dynamic Links to Checkout Sessions

​Key Differences

​Migration Process

​Related API Reference

Create Checkout Session

Preview Checkout Session

前置条件

创建第一个 Checkout Session

API 响应

Request Body

Required Fields

Optional Fields

Usage Examples

1. Simple Single Product Checkout

2. Multi-Product Cart

3. Subscription with Trial Period

4. Pre-confirmed Checkout

5. Checkout with Currency Override

6. Saved Payment Methods for Returning Customers

7. B2B Checkout with Tax ID Collection

8. Dark Theme Checkout with Stacked Discount Codes

9. Regional Payment Methods (UPI for India)

10. BNPL (Buy Now Pay Later) Checkout

11. Using Existing Payment Methods for Instant Checkout

12. Short Links for Cleaner Payment URLs

13. Skip Payment Success Page with Immediate Redirect

14. Forcing a Language

15. Collecting Custom Fields

Previewing Checkout Sessions

Moving from Dynamic Links to Checkout Sessions

Key Differences

Migration Process

Related API Reference