Checkout Sessions

Create secure, hosted checkout experiences for one-time payments and subscriptions with full customization control.

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

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: '[e-mail]',
      name: 'John Doe',
      phone_number: '[phone]'
    },
    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;
}

Python SDK

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": "[e-mail]",
            "name": "John Doe",
            "phone_number": "[phone]"
        },
        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

REST API

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": "[e-mail]",
      "name": "John Doe",
      "phone_number": "[phone]"
    },
    "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

1. Extract the checkout URL

   Get checkout_url from the API response.

2. 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');
   
3. 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

product_cart · array · bắt buộc

Array of products to include in the checkout session. Each product must have a valid product_id from your dashboard.

Bạn có thể kết hợp các sản phẩm thanh toán một lần với một sản phẩm đăng ký trong cùng một phiên. Giỏ hàng cũng có thể chứa từ hai sản phẩm đăng ký trở lên, nhưng khi đó không thể chứa sản phẩm thanh toán một lần. Xem Giỏ hàng nhiều đăng ký. Một giỏ hàng chứa tối đa 20 sản phẩm.

Hiện Product Cart Item Properties

product_id · string · bắt buộc

The unique identifier of the product from your dashboard.

Example: "pdt_123abc456def"

quantity · integer · bắt buộc

Quantity of the product.

Example: 1 for single item, 3 for multiple quantities

addons · array

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

Hiện Addon Item Properties

addon_id · string · bắt buộc

The unique identifier of the addon.

quantity · integer · bắt buộc

Quantity of the addon.

amount · 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.

credit_entitlements · 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.

Hiện Credit Entitlement Override Properties

credit_entitlement_id · string · bắt buộc

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

credits_amount · string · bắt buộc

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

customer · object

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

Attach Existing Customer

Hiện Existing Customer Properties

customer_id · string · bắt buộc

The unique identifier of an existing customer.

Create New Customer

Hiện New Customer Properties

email · string · bắt buộc

Customer’s email address.

name · string

Customer’s full name as it should appear on receipts and invoices.

Example: "John Doe"

phone_number · string

Customer’s phone number in international format. Required for some payment methods and fraud prevention.

Format: Include country code, e.g., "[phone]"

billing_address · object

Billing address information for accurate tax calculation, fraud prevention, and regulatory compliance.

Khi confirm: true, tất cả các trường địa chỉ thanh toán đều bắt buộc, trừ khi minimal_address là true.

Hiện Billing Address Properties

street · string

Complete street address including house number, street name, and apartment/unit number if applicable.

Example: "123 Main St, Apt 4B"

city · string

City or municipality name.

Example: "San Francisco"

state · string

State, province, or region name. Use full names or standard abbreviations.

Example: "California" or "CA"

country · string · bắt buộc

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

zipcode · string

Postal code, ZIP code, or equivalent based on country requirements.

Examples: "94102" (US), "M5V 3A8" (Canada), "SW1A 1AA" (UK)

Payment Configuration

allowed_payment_method_types · 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, paypal

See 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"]

billing_currency · 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 more

Example: "USD" for US Dollars, "EUR" for Euros

Trường này chỉ có hiệu lực khi adaptive pricing được bật. Nếu adaptive pricing bị tắt, API sẽ loại bỏ trường này và tiền tệ được lấy từ giá sản phẩm hoặc quốc gia thanh toán.

show_saved_payment_methods · boolean · mặc định: "false"

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

Session Management

return_url · 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.

cancel_url · 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.

confirm · boolean · mặc định: "false"

If true, finalizes all session details immediately. The API throws an error if required data is missing.

Khi confirm: true:

• Tất cả các trường địa chỉ thanh toán đều bắt buộc (chỉ country và zipcode khi minimal_address là true)
• Có thể cung cấp payment_method_id để xử lý khoản phí ngay lập tức
• Phiên hết hạn sau 15 phút thay vì 24 giờ
• Bắt buộc phải có customer_id hiện có nếu cung cấp payment_method_id

discount_codes · 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.

discount_code · string · không còn sử dụng

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.

metadata · object

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

force_3ds · boolean

Override merchant default 3DS behaviour for this session.

minimal_address · boolean · mặc định: "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

Điều này giảm đáng kể trở ngại khi thanh toán bằng cách loại bỏ các trường biểu mẫu không cần thiết.

Với confirm: true, chỉ zipcode (cùng với country) là bắt buộc; các trường địa chỉ thanh toán khác vẫn là tùy chọn.

payment_method_id · string

Phương thức thanh toán đã lưu thuộc về customer được đính kèm. Yêu cầu confirm: true và customer.customer_id hiện có. Phương thức thanh toán được xác thực về tính đủ điều kiện theo tiền tệ của khoản thanh toán. Khi được đặt, khoản phí sẽ được xử lý ngay lập tức và checkout_url được trả về dưới dạng null. Thay vào đó, hãy sử dụng payment_id được trả về.

short_link · boolean · mặc định: "false"

Nếu là true, trả về URL thanh toán rút gọn thay vì URL phiên đầy đủ.

product_collection_id · string

ID bộ sưu tập sản phẩm cho quy trình thanh toán dựa trên bộ sưu tập. Khi đặt giá trị này, hãy truyền một mảng product_cart rỗng. Không thể áp dụng trước mã giảm giá khi tạo phiên. Xem Bộ sưu tập sản phẩm.

tax_id · string

Mã số thuế của customer (ví dụ: số VAT). Yêu cầu billing_address cùng với một country.

customer_business_name · string

Tên doanh nghiệp hoặc tên pháp lý tùy chọn liên kết với mã số thuế, tối đa 250 ký tự. Khi được cung cấp cùng với một tax_id hợp lệ, tên này được hiển thị trên hóa đơn thay cho tên cá nhân của customer.

mandate_min_amount_inr_paise · integer

Ghi đè ngưỡng mandate cấp merchant (tính bằng paise INR) cho các e-mandate INR trên thẻ Ấn Độ.

Số tiền mandate gửi đến processor là max(this_floor, actual_billing_amount), vì vậy đây thực tế là giới hạn ủy quyền hiển thị cho customer bất cứ khi nào số tiền thanh toán thấp hơn. Khi không được đặt, cài đặt của merchant sẽ được áp dụng; nếu cài đặt đó cũng không được đặt, mặc định hệ thống là ₹15,000.

UI Customization

customization · object

Tùy chỉnh giao diện và hành vi của giao diện thanh toán.

Hiện Customization Properties

theme · string

Chủ đề cho giao diện thanh toán. Các tùy chọn: light, dark hoặc system. Nếu không được cung cấp, thanh toán sẽ sử dụng chủ đề được cấu hình cho doanh nghiệp của bạn trong dashboard.

show_order_details · boolean · mặc định: "true"

Hiển thị phần chi tiết đơn hàng trong giao diện thanh toán.

show_on_demand_tag · boolean · mặc định: "true"

Hiển thị thẻ “on-demand” cho các sản phẩm áp dụng.

force_language · string

Buộc giao diện thanh toán hiển thị bằng một ngôn ngữ cụ thể. Theo mặc định, thanh toán tự động phát hiện ngôn ngữ của trình duyệt customer.

Mã ngôn ngữ được hỗ trợ: ar, ca, de, en, es, fr, he, id, it, ja, ka, ko, ms, nl, pl, pt, ro, ru, sv, th, tr, zh

Ví dụ: "es" cho tiếng Tây Ban Nha, "ja" cho tiếng Nhật

theme_config · object

Cấu hình chủ đề tùy chỉnh với màu cho chế độ sáng và tối, phông chữ và kiểu nút. Đây là phương án thay thế phía server cho tùy chọn themeConfig phía client đã lỗi thời.

Hiện Theme Config Properties

light · object

Cấu hình màu cho chế độ sáng.

dark · object

Cấu hình màu cho chế độ tối.

font_primary_url · string

URL của phông chữ chính. Phải là URL https:// hợp lệ.

font_secondary_url · string

URL của phông chữ phụ. Phải là URL https:// hợp lệ.

font_size · string

Cỡ phông chữ cho giao diện thanh toán. Các tùy chọn: xs, sm, md, lg, xl, 2xl.

font_weight · string

Độ đậm phông chữ cho giao diện thanh toán. Các tùy chọn: normal, medium, bold, extraBold.

pay_button_text · string

Văn bản tùy chỉnh cho nút thanh toán (ví dụ: "Complete Purchase" hoặc "Subscribe Now"). Tối đa 100 ký tự.

radius · string

Bán kính viền cho các phần tử giao diện. Một số theo sau bởi px, rem hoặc em (ví dụ: "4px", "0.5rem", "1em").

Feature Flags

feature_flags · object

Cấu hình các tính năng và hành vi cụ thể cho phiên thanh toán.

Hiện Feature Flags Properties

allow_currency_selection · boolean · mặc định: "true"

Cho phép customer chọn tiền tệ ưa thích trong quá trình thanh toán.

allow_discount_code · boolean · mặc định: "true"

Hiển thị trường nhập mã giảm giá trong giao diện thanh toán.

allow_editing_addons · boolean · mặc định: "false"

Cho phép customer thêm hoặc xóa addon trên sản phẩm đăng ký trong quá trình thanh toán. Chỉ áp dụng cho sản phẩm đăng ký.

allow_phone_number_collection · boolean · mặc định: "true"

Thu thập số điện thoại của customer trong quá trình thanh toán.

require_phone_number · boolean · mặc định: "false"

Yêu cầu customer cung cấp số điện thoại để hoàn tất thanh toán. Yêu cầu allow_phone_number_collection cũng phải là true.

require_cardholder_name · boolean · mặc định: "false"

Yêu cầu customer nhập tên trên thẻ để thanh toán bằng thẻ. Các phương thức thanh toán khác bỏ qua cờ này.

allow_tax_id · boolean · mặc định: "true"

Cho phép customer nhập mã số thuế.

require_tax_id · boolean · mặc định: "false"

Yêu cầu customer cung cấp Tax ID (số GST tại Ấn Độ, số VAT tại EU) trước khi có thể hoàn tất thanh toán.

Khi được bật, Mua với tư cách doanh nghiệp được chọn trước và khóa trên trang thanh toán, đồng thời Tên doanh nghiệp và Số mã số thuế trở thành bắt buộc. Xem Thanh toán B2B để biết đầy đủ hành vi khi thanh toán.

allow_tax_id cũng phải là true. Nếu không, request sẽ bị từ chối với 400 và thông báo feature_flags.require_tax_id: cannot be true when allow_tax_id is false. Với confirm: true, request phải bao gồm tax_id không chỉ chứa khoảng trắng; nếu không, request sẽ bị từ chối với 422.

always_create_new_customer · boolean · mặc định: "false"

Buộc tạo bản ghi customer mới thay vì cập nhật các bản ghi hiện có.

allow_customer_editing_email · boolean

Cho phép customer chỉnh sửa địa chỉ email trong quá trình thanh toán.

allow_customer_editing_name · boolean

Cho phép customer chỉnh sửa tên trong quá trình thanh toán.

allow_customer_editing_street · boolean

Cho phép customer chỉnh sửa địa chỉ đường phố trong quá trình thanh toán.

allow_customer_editing_city · boolean

Cho phép customer chỉnh sửa thành phố trong quá trình thanh toán.

allow_customer_editing_state · boolean

Cho phép customer chỉnh sửa bang/tỉnh trong quá trình thanh toán.

allow_customer_editing_country · boolean

Cho phép customer chỉnh sửa quốc gia trong quá trình thanh toán.

allow_customer_editing_zipcode · boolean

Cho phép customer chỉnh sửa mã bưu chính trong quá trình thanh toán.

allow_customer_editing_tax_id · boolean

Cho phép customer nhập hoặc chỉnh sửa mã số thuế trong quá trình thanh toán.

allow_customer_editing_business_name · boolean · mặc định: "false"

Cho phép customer cung cấp hoặc chỉnh sửa tên doanh nghiệp liên kết với mã số thuế. Hoạt động độc lập với allow_customer_editing_tax_id: một trong hai cờ (hoặc allow_tax_id) là đủ để customer ghi đè tên doanh nghiệp của phiên. Thông thường được đặt cùng với allow_customer_editing_tax_id.

redirect_immediately · boolean · mặc định: "false"

Bỏ qua trang thành công thanh toán mặc định và chuyển hướng customer ngay lập tức đến return_url sau khi hoàn tất thanh toán.

Sử dụng tùy chọn này khi bạn có trang thành công tùy chỉnh mang lại trải nghiệm người dùng tốt hơn, hoặc cho ứng dụng di động và các quy trình thanh toán được nhúng.

single_page · boolean · mặc định: "false"

Nếu là true, phiên sử dụng quy trình thanh toán một trang: trang khởi tạo payment khi tải và xác nhận payment ngay tại đó, không có trang payment riêng.

Custom Fields

custom_fields · array

Thu thập thêm thông tin từ customer trong quá trình thanh toán bằng các trường biểu mẫu tùy chỉnh. Bạn có thể xác định tối đa 5 trường tùy chỉnh cho mỗi phiên thanh toán. Phản hồi của customer được đưa vào payload webhook và có sẵn qua API.

Hiện Custom Field Properties

key · string · bắt buộc

Mã nhận dạng duy nhất cho trường này. Được sử dụng làm key trong payload webhook và response API.

Ví dụ: "company_name", "referral_source", "team_size"

label · string · bắt buộc

Nhãn hiển thị cho customer trên biểu mẫu thanh toán.

Ví dụ: "Company Name", "How did you hear about us?", "Team Size"

field_type · string · bắt buộc

Loại trường xác định các quy tắc xác thực input.

Các loại có sẵn: text, number, email, url, date, dropdown, boolean

required · boolean · mặc định: "false"

Cho biết trường này có phải được điền trước khi hoàn tất thanh toán hay không.

placeholder · string

Văn bản placeholder hiển thị trong trường input.

options · array

Danh sách tùy chọn cho loại trường dropdown. Bắt buộc khi field_type là dropdown, bị bỏ qua đối với các loại khác.

Ví dụ: ["Google", "Twitter", "Friend referral", "Other"]

Phản hồi của customer đối với các trường tùy chỉnh được đưa vào:

• Webhooks: payment.succeeded, subscription.active và các payload sự kiện liên quan khác chứa mảng custom_field_responses
• Response API: Các object payment và subscription bao gồm custom_field_responses

Subscription Configuration

subscription_data · object

Cấu hình bổ sung cho các phiên thanh toán chứa sản phẩm đăng ký.

Hiện Subscription Data Properties

trial_period_days · integer

Số ngày của thời gian dùng thử trước lần tính phí đầu tiên. Phải nằm trong khoảng từ 0 đến 10000 ngày.

Không thể đặt số tiền dùng thử có phí cho từng phiên. Thay vào đó, hãy cấu hình trial_amount trên giá định kỳ của sản phẩm. Xem Dùng thử có phí.

on_demand · object

Cấu hình subscription on-demand cho hình thức tính phí theo mức sử dụng hoặc theo đồng hồ đo.

Hiện On-Demand Properties

mandate_only · boolean · bắt buộc

Nếu đặt thành true, không thực hiện bất kỳ khoản phí nào mà chỉ ủy quyền chi tiết phương thức thanh toán để sử dụng trong tương lai.

product_price · integer

Giá sản phẩm cho khoản phí ban đầu của customer. Nếu không được chỉ định, giá đã lưu của sản phẩm sẽ được sử dụng.

Định dạng: Được biểu diễn theo mệnh giá nhỏ nhất của tiền tệ (ví dụ: cent đối với USD). Ví dụ, 100 = $1.00.

product_currency · string

Tiền tệ tùy chọn của giá sản phẩm. Nếu không được chỉ định, mặc định là tiền tệ của sản phẩm.

product_description · string

Mô tả sản phẩm tùy chọn ghi đè cho mục thanh toán và line item. Nếu không được chỉ định, mô tả đã lưu của sản phẩm sẽ được sử dụng.

adaptive_currency_fees_inclusive · boolean

Cho biết phí adaptive currency có được đưa vào giá sản phẩm (true) hay cộng thêm bên ngoài (false). Bị bỏ qua nếu adaptive pricing không được bật.

​

Ví dụ về cách sử dụng

​

Thanh toán đơn giản cho một sản phẩm

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

​

Giỏ hàng nhiều sản phẩm

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

​

Giỏ hàng nhiều đăng ký

Để bán nhiều sản phẩm đăng ký trong một lần thanh toán, hãy thêm từ hai sản phẩm đăng ký trở lên vào product_cart. Customer thanh toán một lần, còn Dodo Payments tạo một payment, một invoice và một subscription cho mỗi sản phẩm. Mỗi subscription có chu kỳ thanh toán riêng và tự gia hạn độc lập, vì vậy sản phẩm theo tháng và sản phẩm theo năm có thể cùng nằm trong một giỏ hàng.

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: '[e-mail]',
    name: 'Jane Smith'
  },
  return_url: 'https://yoursite.com/success'
});

Giỏ hàng nhiều đăng ký có các giới hạn sau:

• Không thể chứa sản phẩm thanh toán một lần. API từ chối request với 422.
• Chứa tối đa 20 sản phẩm đăng ký.
• Không thể liệt kê cùng một sản phẩm hai lần. Để bán nhiều hơn một đơn vị sản phẩm, hãy đặt quantity thay vào đó.
• Không thể sử dụng hình thức tính phí on-demand (subscription_data.on_demand).
• Mã giảm giá áp dụng cho giỏ hàng được tính là một lần sử dụng.

subscription_data.trial_period_days áp dụng cho mọi subscription trong giỏ hàng. Nếu không có giá trị này, mỗi subscription sử dụng thời gian dùng thử được đặt trên sản phẩm riêng. Khi bạn không đặt giá trị này và Prevent Trial Misuse đang bật, sản phẩm mà customer đã dùng thử trước đó sẽ bắt đầu mà không có thời gian dùng thử.

Payment kết quả có is_multi_subscription: true và liệt kê mọi subscription mà payment khởi tạo trong subscription_ids. subscription_id của payment là null vì không có subscription riêng lẻ nào sở hữu payment. Webhook payment.succeeded chứa các trường tương tự. Đọc is_multi_subscription để xác định loại payment, không phải độ dài của subscription_ids.

Sau khi payment thành công, bạn nhận được một sự kiện payment.succeeded cho giỏ hàng và một sự kiện subscription.active cho mỗi subscription. Từ đó, mỗi subscription tự gia hạn, thay đổi plan và hủy độc lập, với một invoice riêng cho mỗi lần gia hạn.

Tất cả subscription từ một giỏ hàng dùng chung phương thức thanh toán mà customer đã sử dụng khi thanh toán. Khi bạn cập nhật phương thức thanh toán của một subscription, Dodo Payments chuyển phương thức thanh toán mới sang mọi subscription từ cùng giỏ hàng có cùng settlement currency và billing currency, đồng thời là active, on_hold, past_due hoặc paused. Mọi subscription từ một giỏ hàng bắt đầu với cùng settlement currency và billing currency, ngay cả khi sản phẩm của chúng có tiền tệ giá khác nhau. Một thay đổi sau đó, chẳng hạn thay đổi plan, có thể chuyển subscription sang settlement currency hoặc billing currency khác. Subscription đó giữ phương thức thanh toán cũ, vì vậy hãy cập nhật riêng. Đối với subscription on_hold, bản cập nhật chỉ thử lại invoice chưa thanh toán của subscription đó.

​

Subscription có thời gian dùng thử

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

​

Thanh toán đã xác nhận trước

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

​

Thanh toán có ghi đè tiền tệ

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

​

Phương thức thanh toán đã lưu cho customer quay lại

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

​

Thanh toán B2B có thu thập mã số thuế

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_enterprise_plan',
      quantity: 1
    }
  ],
  customer: {
    email: '[e-mail]',
    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'
});

​

Thanh toán chủ đề tối với các mã giảm giá xếp chồng

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

​

Phương thức thanh toán theo khu vực (UPI cho Ấn Độ)

Để biết thông tin chi tiết về cấu hình và kiểm thử UPI, xem trang Phương thức thanh toán tại Ấn Độ.

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_123',
      quantity: 1
    }
  ],
  customer: {
    email: '[e-mail]',
    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'
});

​

Thanh toán BNPL (Mua trước, trả sau)

Để biết thông tin chi tiết về cấu hình và kiểm thử BNPL, xem trang Mua trước, trả sau (BNPL).

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

​

Thanh toán tức thì với phương thức thanh toán hiện có

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

​

Liên kết rút gọn cho URL payment gọn gàng hơn

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

​

Bỏ qua trang thành công payment với chuyển hướng ngay lập tức

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

​

Buộc sử dụng một ngôn ngữ

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

​

Thu thập các trường tùy chỉnh

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_123',
      quantity: 1
    }
  ],
  customer: {
    email: '[e-mail]',
    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'
});

​

Xem trước các phiên thanh toán

Sử dụng endpoint Preview Checkout Session để tính giá, thuế và tổng tiền trước khi tạo phiên. Điều này hữu ích khi hiển thị thông tin giá chính xác trên trang web của bạn.

current_breakup.subtotal được xem trước đã phản ánh Purchasing Power Parity và Charm Pricing nếu các tính năng này áp dụng cho sản phẩm.

Khi giỏ hàng chứa sản phẩm đăng ký, response xem trước cũng trả về một next_billing_date — bản xem trước của ngày thanh toán sắp tới, để bạn có thể hiển thị ngày này trước khi subscription được tạo. Ngày được tính tương đối với hiện tại: now + trial period khi áp dụng thời gian dùng thử, nếu không thì now + one payment frequency. Trường này bị bỏ qua đối với giỏ hàng chỉ chứa sản phẩm thanh toán một lần. Đây là ước tính dựa trên thời điểm xem trước; next_billing_date chính thức được đặt khi subscription được kích hoạt.

Bản xem trước cũng trả về trial_period_days (thời lượng dùng thử thực tế, miễn phí hoặc có phí) và trial_amount (phí dùng thử trên mỗi đơn vị sau giảm giá, tính theo đơn vị nhỏ nhất của tiền tệ giá). trial_amount chỉ xuất hiện đối với dùng thử có phí và là null đối với dùng thử miễn phí hoặc không dùng thử. Sử dụng current_breakup cho tổng tiền đã tính thuế thực sự phải trả hôm nay.

Đối với giỏ hàng nhiều đăng ký, response cũng trả về một mảng subscriptions với một mục cho mỗi subscription: product_id, amount_due_now, tax_due_now, recurring_amount, recurring_tax, trial_period_days và next_billing_date. next_billing_date cấp cao nhất là ngày sớm nhất trong giỏ hàng, còn trial_period_days và trial_amount cấp cao nhất là null. Đọc các khoản tiền từ subscriptions và current_breakup. recurring_breakup cộng tổng số tiền gia hạn của mọi subscription, ngay cả khi chúng gia hạn vào các ngày khác nhau, vì vậy hãy đọc từng lần gia hạn từ subscriptions.

Node.js 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);

Python SDK

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

REST API

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"]
  }'

​

Di chuyển từ Dynamic Links

Nếu bạn đang sử dụng Dynamic Links, Checkout Sessions mang lại nhiều tính linh hoạt hơn. Với Dynamic Links, bạn phải cung cấp đầy đủ địa chỉ thanh toán của customer. Với Checkout Sessions, bạn có thể truyền bất kỳ thông tin nào mình có và quy trình thanh toán sẽ thu thập phần còn lại.

Ví dụ:

• Chỉ cung cấp quốc gia thanh toán của customer, sau đó thanh toán sẽ thu thập các thông tin còn lại.
• Hoặc cung cấp toàn bộ thông tin và đặt confirm: true để chuyển thẳng đến trang payment.

Việc di chuyển rất đơn giản: cập nhật integration để sử dụng API Checkout Sessions hoặc phương thức SDK, điều chỉnh payload request cho phù hợp với định dạng Checkout Sessions là xong. Không cần xử lý thêm.

​

Tài nguyên liên quan

Overlay Checkout

Mở thanh toán dưới dạng modal overlay trên trang của bạn

Inline Checkout

Nhúng thanh toán trực tiếp vào trang của bạn

Mobile Integration

Tích hợp thanh toán vào ứng dụng di động native

Webhooks

Lắng nghe các sự kiện payment và subscription

Payment Methods

Các phương thức thanh toán được hỗ trợ theo khu vực

Subscriptions

Thanh toán định kỳ và quản lý subscription