Checkout Sessions - Dodo Payments Documentation

Quick Start

Create your first checkout session in under 5 minutes

API Reference

Full API documentation and interactive testing

Preview Endpoint

Calculate pricing and taxes before creating a session

Session Validity: Checkout sessions expire after 24 hours by default, or 15 minutes when confirm: true.

Single-Use Links: The checkout_url is not reusable. Generate a fresh session for each customer and payment attempt rather than sharing or reusing a link.

Prerequisites

You need:

An active Dodo Payments merchant account
API credentials from Developer → API Keys in the dashboard
At least one product created in Products

Creating Your First Checkout Session

Node.js SDK
Python SDK
REST API

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
});

async function createCheckoutSession() {
  const session = await client.checkoutSessions.create({
    product_cart: [
      {
        product_id: 'pdt_123',
        quantity: 1
      }
    ],
    customer: {
      email: 'customer@example.com',
      name: 'John Doe',
      phone_number: '+1234567890'
    },
    billing_address: {
      street: '123 Main St',
      city: 'San Francisco',
      state: 'CA',
      country: 'US',
      zipcode: '94102'
    },
    return_url: 'https://yoursite.com/checkout/success'
  });

  console.log('Checkout URL:', session.checkout_url);
  return session;
}

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",
)

def create_checkout_session():
    session = client.checkout_sessions.create(
        product_cart=[
            {
                "product_id": "pdt_123",
                "quantity": 1
            }
        ],
        customer={
            "email": "customer@example.com",
            "name": "John Doe",
            "phone_number": "+1234567890"
        },
        billing_address={
            "street": "123 Main St",
            "city": "San Francisco",
            "state": "CA",
            "country": "US",
            "zipcode": "94102"
        },
        return_url="https://yoursite.com/checkout/success"
    )

    print(f"Checkout URL: {session.checkout_url}")
    return session

curl -X POST https://test.dodopayments.com/checkouts \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_cart": [
      {
        "product_id": "pdt_123",
        "quantity": 1
      }
    ],
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe",
      "phone_number": "+1234567890"
    },
    "billing_address": {
      "street": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "zipcode": "94102"
    },
    "return_url": "https://yoursite.com/checkout/success"
  }'

API Response

All methods return:

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

Only session_id is guaranteed to be present. When payment_method_id is provided, the charge processes immediately and checkout_url is null. Use the returned payment_id instead. When confirm: true, the payment is created at session-creation time, and the response also includes payment_id, client_secret, and publishable_key for use with the Dodo Payments checkout SDK.

Redirect Your Customer

Extract the checkout URL

Get checkout_url from the API response.

Redirect to checkout

Send your customer to the URL:

window.location.href = session.checkout_url;

Alternatively, open in a new window:

window.open(session.checkout_url, '_blank');

Handle the return

After payment, customers are redirected to your return_url with query parameters:

Parameter	Type	Condition
`payment_id`	string	Always present for one-time payments
`subscription_id`	string	Always present for subscriptions
`status`	string	Always present
`license_key`	string	Present if the product has license keys enabled. Comma-separated if multiple keys
`email`	string	Present if the customer has an email on record

Example redirect:

https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com

Instead of redirecting, you can embed checkout directly in your page using Overlay Checkout (modal), Inline Checkout (embedded), or Mobile SDKs (native apps). All consume the same session URL.

Check Session Status

To check a session’s status, call Get Checkout Session (GET /checkouts/{id}). The response has the session id, created_at, customer_email, and customer_name, plus payment_id and payment_status. Both payment fields are null while the customer is still entering details. After the customer submits payment, payment_status holds the payment’s status, such as succeeded, failed, or processing. Use webhooks as the source of truth for fulfillment.

Request Body

Required Fields

array

必填

Array of products to include in the checkout session. Each product must have a valid product_id from your dashboard.您可以在同一会话中将一次性付款产品与一个订阅产品组合使用。购物车也可以包含两个或更多订阅产品，但此时不能包含一次性付款产品。请参阅多订阅购物车。购物车最多可包含 20 个产品。

显示 Product Cart Item Properties

string

必填

The unique identifier of the product from your dashboard.Example: "pdt_123abc456def"

integer

必填

Quantity of the product.Example: 1 for single item, 3 for multiple quantities

array

Array of addons to attach to the product. Only valid for subscription products.

显示 Addon Item Properties

string

必填

The unique identifier of the addon.

integer

必填

Quantity of the addon.

integer

Amount the customer pays if pay-what-you-want is enabled on the product. Represented in the lowest denomination of the currency (e.g., cents for USD). For example, 100 = $1.00.Ignored if pay-what-you-want is disabled.

array

Per-session overrides for credit entitlements already attached to this product. Use this to grant a different number of credits for this single session without creating a separate product.Each credit_entitlement_id must already be attached to the product. This field overrides only the credits_amount granted when this session is fulfilled; product-level credit entitlement settings (expiration, rollover, etc.) still apply.

显示 Credit Entitlement Override Properties

string

必填

ID of the credit entitlement to override. Must already be attached to the product.

string

必填

Number of credits to grant for this checkout session, overriding the product-level credits_amount. Must be greater than zero.

Find Your Product IDs: You can find product IDs in your Dodo Payments dashboard under Products → View Details, or by using the List Products API.

Optional Fields

Customer Information

object

Customer information. You can either attach an existing customer using their ID or create a new customer record during checkout.

Attach Existing Customer
Create New Customer

显示 Existing Customer Properties

string

必填

The unique identifier of an existing customer.

显示 New Customer Properties

string

必填

Customer’s email address.

string

Customer’s full name as it should appear on receipts and invoices.Example: "John Doe"

string

Customer’s phone number in international format. Required for some payment methods and fraud prevention.Format: Include country code, e.g., "+1234567890"

object

Billing address information for accurate tax calculation, fraud prevention, and regulatory compliance.当 confirm: true 时，所有账单地址字段都变为必填，除非 minimal_address 为 true。

显示 Billing Address Properties

string

Complete street address including house number, street name, and apartment/unit number if applicable.Example: "123 Main St, Apt 4B"

string

City or municipality name.Example: "San Francisco"

string

State, province, or region name. Use full names or standard abbreviations.Example: "California" or "CA"

string

必填

Two-letter ISO country code (ISO 3166-1 alpha-2). Always required when billing_address is provided.Examples: "US", "CA", "GB", "DE"

Country Code Reference

View complete list of supported countries and their ISO codes

string

Postal code, ZIP code, or equivalent based on country requirements.Examples: "94102" (US), "M5V 3A8" (Canada), "SW1A 1AA" (UK)

Payment Configuration

array

Control which payment methods are available to customers during checkout. This helps optimize for specific markets or business requirements.Common options: credit, debit, upi_collect, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, cashapp, ach, multibanco, bancontact_card, eps, ideal, blik, gcash, ali_pay_hk, fps, touch_n_go, paypalSee the Create Checkout Session API reference for the complete list.

Always include credit and debit as fallback options to prevent checkout failures when preferred payment methods are unavailable.

Example:

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

string

Override the default currency selection with a fixed billing currency. Uses ISO 4217 currency codes.Supported Currencies: USD, EUR, GBP, CAD, AUD, INR, and moreExample: "USD" for US Dollars, "EUR" for Euros此字段仅在启用自适应定价时生效。如果禁用自适应定价，API 会丢弃此字段，货币将取自产品价格或账单国家/地区。

boolean

默认值:"false"

Display previously saved payment methods for returning customers, improving checkout speed and user experience.

Session Management

string

URL to redirect customers after payment completion. Dodo Payments appends query parameters to your URL on redirect (see the redirect table above).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

Use the license_key and email query parameters to display license keys or send a confirmation immediately on your return page, without needing an extra API call.

string

URL to redirect customers when they click the back button or cancel the checkout session. If not provided, the back button will not be displayed.Set a cancel_url to give customers a clear way to return to your site without completing the purchase.

boolean

默认值:"false"

If true, finalizes all session details immediately. The API throws an error if required data is missing.当 confirm: true 时：

所有账单地址字段都变为必填（当 minimal_address 为 true 时，仅 country 和 zipcode 为必填）
可以提供 payment_method_id 以立即处理扣款
会话将在 15 分钟后过期，而不是 24 小时
如果提供了 payment_method_id，则必须已有 customer_id

array

Apply one or more stacked discount codes to the checkout session. Codes are applied in array order (the first code reduces the starting price, the second reduces the already-discounted price, and so on), up to a maximum of 20 codes per session.When Purchasing Power Parity is enabled, the starting price is the PPP-adjusted amount, not the base price.

discount_codes: ['WELCOME10', 'BLACKFRIDAY20']

The singular discount_code field below is deprecated but still fully supported. It cannot be combined with discount_codes in the same request.

string

已弃用

Deprecated — prefer discount_codes for new integrations. This field still works for backward compatibility, but cannot be combined with discount_codes in the same request.

object

Custom key-value pairs to store additional information about the session.

boolean

Override merchant default 3DS behaviour for this session.

boolean

默认值:"false"

Enable minimal address collection mode. When enabled, the checkout only collects:

Country: Always required for tax determination
ZIP/Postal code: Only in regions where it’s necessary for sales tax, VAT, or GST calculation

通过消除不必要的表单字段，这可以显著减少结账阻力。使用 confirm: true 时，只需填写 zipcode（以及 country）；其他账单地址字段仍为可选。

string

属于所附客户的已保存支付方式。需要 confirm: true 和现有的 customer.customer_id。系统会根据付款货币验证该支付方式是否符合条件。设置后会立即处理扣款，并将 checkout_url 作为 null 返回。请改用返回的 payment_id。

boolean

默认值:"false"

如果为 true，则返回缩短的结账 URL，而不是完整的会话 URL。

string

基于产品集合的结账流程所使用的产品集合 ID。设置此项时，请传入空的 product_cart 数组。创建会话时不能预先应用折扣码。请参阅产品集合。

string

客户的税号（例如 VAT 号码）。需要将 billing_address 与 country 一起使用。

string

与税号关联的可选企业或法定名称，最多 250 个字符。若与有效的 tax_id 一起提供，该名称会显示在发票上，而不是客户的个人姓名。

integer

为印度银行卡的 INR 电子委托设置商户级委托下限的覆盖值（以 INR 派士为单位）。发送给处理方的委托金额为 max(this_floor, actual_billing_amount)，因此当账单金额较低时，这实际上就是面向客户的授权上限。未设置时使用商户设置；商户设置也未设置时，使用系统默认值 ₹15,000。

UI Customization

object

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

显示 Customization Properties

string

结账界面的主题。选项包括：light、dark 或 system。如果未提供，结账流程将使用您在控制面板中为企业配置的主题。

boolean

默认值:"true"

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

boolean

默认值:"true"

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

string

强制结账界面以指定语言呈现。默认情况下，结账流程会自动检测客户的浏览器语言。支持的语言代码：ar、ca、de、en、es、fr、he、id、it、ja、ka、ko、ms、nl、pl、pt、ro、ru、sv、th、tr、zh示例：西班牙语使用 "es"，日语使用 "ja"

object

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

显示 Theme Config Properties

object

浅色模式颜色配置。

object

深色模式颜色配置。

string

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

string

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

string

结账 UI 的字体大小。选项包括：xs、sm、md、lg、xl、2xl。

string

结账 UI 的字体粗细。选项包括：normal、medium、bold、extraBold。

string

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

string

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

Feature Flags

object

配置结账会话的特定功能和行为。

显示 Feature Flags Properties

boolean

默认值:"true"

允许客户在结账时选择首选货币。

boolean

默认值:"true"

在结账界面中显示折扣码输入字段。

boolean

默认值:"false"

允许客户在结账时为订阅产品添加或移除附加项。仅适用于订阅产品。

boolean

默认值:"true"

在结账时收集客户电话号码。

boolean

默认值:"false"

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

boolean

默认值:"false"

要求客户输入卡片上的姓名才能使用银行卡付款。其他支付方式会忽略此标志。

boolean

默认值:"true"

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

boolean

默认值:"false"

要求客户提供税号（印度的 GST 号码、欧盟的 VAT 号码）后才能完成结账。启用后，结账页面会预先选中并锁定以企业身份购买，同时企业名称和税号变为必填项。有关完整的结账行为，请参阅 B2B 付款。allow_tax_id 也必须为 true。否则，请求会被拒绝，并返回 400 及消息 feature_flags.require_tax_id: cannot be true when allow_tax_id is false。使用 confirm: true 时，请求必须包含非空的 tax_id，否则会被拒绝，并返回 422。

boolean

默认值:"false"

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

boolean

允许客户在结账时编辑电子邮件地址。

boolean

允许客户在结账时编辑姓名。

boolean

允许客户在结账时编辑街道地址。

boolean

允许客户在结账时编辑城市。

boolean

允许客户在结账时编辑州/省。

boolean

允许客户在结账时编辑国家/地区。

boolean

允许客户在结账时编辑邮政编码。

boolean

允许客户在结账时输入或编辑税号。

boolean

默认值:"false"

允许客户提供或编辑与税号关联的企业名称。独立于 allow_customer_editing_tax_id 工作：任一标志（或 allow_tax_id）都足以让客户覆盖会话的企业名称。通常与 allow_customer_editing_tax_id 一起设置。

boolean

默认值:"false"

跳过默认的付款成功页面，并在付款完成后立即将客户重定向到 return_url。当您有可提供更佳用户体验的自定义成功页面，或用于移动应用和嵌入式结账流程时，请使用此选项。

boolean

默认值:"false"

如果为 true，会话将使用单页结账流程：页面加载时初始化付款并在当前页面确认付款，不会打开单独的付款页面。

Custom Fields

array

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

显示 Custom Field Properties

string

必填

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

string

必填

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

string

必填

用于确定输入验证规则的字段类型。可用类型：text、number、email、url、date、dropdown、boolean

boolean

默认值:"false"

该字段是否必须填写才能完成结账。

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

包含订阅产品的结账会话的其他配置。

显示 Subscription Data Properties

integer

首次扣款前试用期的天数。必须介于 0 到 10000 天之间。不能按会话设置付费试用金额。请改为在产品的周期性价格上配置 trial_amount。请参阅付费试用。

object

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

显示 On-Demand Properties

boolean

必填

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

integer

向客户收取的初始扣款所使用的产品价格。如果未指定，则使用产品的存储价格。格式：以货币的最小面额表示（例如 USD 的美分）。例如，100 = $1.00。

string

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

string

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

boolean

是否应将自适应货币费用包含在产品价格中（true），还是在其基础上另行添加（false）。如果未启用自适应定价，则忽略此项。

使用示例

简单的单产品结账

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'
});

多产品购物车

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

多订阅购物车

要在一次结账中销售多个订阅产品，请将两个或更多订阅产品添加到 product_cart。客户只需付款一次，Dodo Payments 会为每个产品创建一笔付款、一张发票和一个订阅。每个订阅都有自己的计费周期并独立续订，因此月付产品和年付产品可以共用一个购物车。

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

多订阅购物车有以下限制：

不能包含一次性付款产品。API 会使用 422 拒绝请求。
最多可包含 20 个订阅产品。
不能两次列出同一产品。要销售一个产品的多个单位，请改为设置 quantity。
不能使用按需计费（subscription_data.on_demand）。
应用于购物车的折扣码计为一次兑换。

subscription_data.trial_period_days 会应用于购物车中的每个订阅。没有此项时，每个订阅会使用其自身产品上设置的试用期。如果未设置此项且已启用防止试用滥用，客户已经试用过的产品将不再提供试用期。生成的付款具有 is_multi_subscription: true，并在 subscription_ids 中列出其启动的每个订阅。其 subscription_id 为 null，因为没有任何单个订阅拥有该付款。payment.succeeded webhook 携带相同字段。请读取 is_multi_subscription 来查找付款类型，而不要根据 subscription_ids 的长度判断。付款成功后，您会收到一个购物车的 payment.succeeded 事件，以及每个订阅各一个 subscription.active 事件。此后，每个订阅都会独立续订、变更计划和取消，并且每次续订都有自己的发票。同一购物车中的所有订阅共享客户在结账时使用的支付方式。当您更新其中一个订阅的支付方式时，Dodo Payments 会将新支付方式移至同一购物车中、具有相同结算货币和账单货币且处于 active、on_hold、past_due 或 paused 状态的所有订阅。购物车中的每个订阅都以相同的结算货币和账单货币开始，即使其产品使用不同的价格货币也是如此。之后的变更（例如计划变更）可能会使订阅转为其他结算货币或账单货币。该订阅会保留旧的支付方式，因此需要单独更新。对于 on_hold 订阅，此更新只会重试该订阅未支付的发票。

带试用期的订阅

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

预确认结账

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_123',
      quantity: 1
    }
  ],
  customer: {
    customer_id: 'cus_existing_customer_id'
  },
  billing_address: {
    street: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    country: 'US',
    zipcode: '94102'
  },
  confirm: true,
  return_url: 'https://yoursite.com/success'
});

覆盖货币的结账

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

回头客使用已保存的支付方式

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_123',
      quantity: 1
    }
  ],
  customer: {
    customer_id: 'cus_existing_customer_id'
  },
  show_saved_payment_methods: true,
  return_url: 'https://yoursite.com/success'
});

收集税号的 B2B 结账

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_enterprise_plan',
      quantity: 1
    }
  ],
  customer: {
    email: 'procurement@company.com',
    name: 'Jane Smith'
  },
  billing_address: {
    street: '456 Business Ave',
    city: 'London',
    country: 'GB',
    zipcode: 'SW1A 1AA'
  },
  feature_flags: {
    require_tax_id: true
  },
  return_url: 'https://yoursite.com/success'
});

深色主题结账与堆叠折扣码

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

区域支付方式（印度 UPI）

有关 UPI 配置和测试的详细信息，请参阅印度支付方式页面。

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_123',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  },
  billing_address: {
    street: '123 Main St',
    city: 'Bangalore',
    state: 'KA',
    country: 'IN',
    zipcode: '560001'
  },
  billing_currency: 'INR',
  allowed_payment_method_types: ['upi_intent', 'credit', 'debit'],
  return_url: 'https://yoursite.com/success'
});

BNPL（先买后付）结账

有关 BNPL 配置和测试的详细信息，请参阅先买后付 (BNPL)页面。

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

使用现有支付方式的即时结账

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_123',
      quantity: 1
    }
  ],
  customer: {
    customer_id: 'cus_existing_customer_id'
  },
  payment_method_id: 'pm_existing_payment_method_id',
  confirm: true,
  return_url: 'https://yoursite.com/success'
});

更简洁的付款 URL 的短链接

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

跳过付款成功页面并立即重定向

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

强制指定语言

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

收集自定义字段

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_123',
      quantity: 1
    }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe'
  },
  custom_fields: [
    {
      key: 'company_name',
      label: 'Company Name',
      field_type: 'text',
      required: true
    },
    {
      key: 'referral_source',
      label: 'How did you hear about us?',
      field_type: 'dropdown',
      options: ['Google', 'Twitter', 'Friend referral', 'Other'],
      required: true
    }
  ],
  return_url: 'https://yoursite.com/success'
});

预览结账会话

使用 Preview Checkout Session endpoint，在创建会话前计算价格、税费和总额。这有助于在您的网站上显示准确的价格信息。

预览的 current_breakup.subtotal 已在适用时反映购买力平价和魅力定价。

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

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

对于多订阅购物车，响应还会返回 subscriptions 数组，其中每个订阅对应一个条目：product_id、amount_due_now、tax_due_now、recurring_amount、recurring_tax、trial_period_days 和 next_billing_date。顶层 next_billing_date 是购物车中的最早日期，顶层 trial_period_days 和 trial_amount 为 null。请从 subscriptions 和 current_breakup 读取金额。即使每个订阅的续订日期不同，recurring_breakup 也会汇总所有订阅的续订金额，因此请从 subscriptions 读取每次续订金额。

Node.js SDK
Python SDK
REST API

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}")

curl -X POST https://test.dodopayments.com/checkouts/preview \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_cart": [
      {
        "product_id": "pdt_123",
        "quantity": 1
      }
    ],
    "billing_address": {
      "country": "US",
      "state": "CA",
      "zipcode": "94102"
    },
    "discount_codes": ["SAVE20"]
  }'

从 Dynamic Links 迁移

如果您正在使用 Dynamic Links，Checkout Sessions 可提供更大的灵活性。使用 Dynamic Links 时，您必须提供客户完整的账单地址。使用 Checkout Sessions 时，您可以传入已有的任意信息，结账流程会收集其余信息。例如：

仅提供客户的账单国家/地区，结账流程会收集其余详细信息。
或提供所有信息，并将 confirm: true 设置为直接跳转到付款页面。

迁移过程很简单：更新集成以使用 Checkout Sessions API 或 SDK 方法，调整请求 payload 以匹配 Checkout Sessions 格式，即可完成迁移。无需额外处理。

Overlay Checkout

在页面上以模态覆盖层打开结账

Inline Checkout

将结账直接嵌入页面

Mobile Integration

在原生移动应用中集成结账

Webhooks

监听付款和订阅事件

Payment Methods

按地区划分的支持支付方式

Subscriptions

周期性计费和订阅管理

Quick Start

API Reference

Preview Endpoint

​Prerequisites

​Creating Your First Checkout Session

​API Response

​Redirect Your Customer

​Check Session Status

​Request Body

​Required Fields

​Optional Fields

Country Code Reference

​使用示例

​简单的单产品结账

​多产品购物车

​多订阅购物车

​带试用期的订阅

​预确认结账

​覆盖货币的结账

​回头客使用已保存的支付方式

​收集税号的 B2B 结账

​深色主题结账与堆叠折扣码

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

​BNPL（先买后付）结账

​使用现有支付方式的即时结账

​更简洁的付款 URL 的短链接

​跳过付款成功页面并立即重定向

​强制指定语言

​收集自定义字段

​预览结账会话

​从 Dynamic Links 迁移

​相关资源

Overlay Checkout

Inline Checkout

Mobile Integration

Webhooks

Payment Methods

Subscriptions

Prerequisites

Creating Your First Checkout Session

API Response

Redirect Your Customer

Check Session Status

Request Body

Required Fields

Optional Fields

使用示例

简单的单产品结账

多产品购物车

多订阅购物车

带试用期的订阅

预确认结账

覆盖货币的结账

回头客使用已保存的支付方式

收集税号的 B2B 结账

深色主题结账与堆叠折扣码

区域支付方式（印度 UPI）

BNPL（先买后付）结账

使用现有支付方式的即时结账

更简洁的付款 URL 的短链接

跳过付款成功页面并立即重定向

强制指定语言

收集自定义字段

预览结账会话

从 Dynamic Links 迁移

相关资源