Checkout Sessions - Dodo Payments Documentation

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.

Prerequisites

Dodo Payments Account

You’ll need an active Dodo Payments merchant account with API access.

API Credentials

Generate your API credentials from the Dodo Payments dashboard:

Products Setup

Create your products in the Dodo Payments dashboard before implementing checkout sessions.

Creating Your First Checkout Session

Node.js SDK
Python SDK
REST API

import DodoPayments from 'dodopayments';

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

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

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

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

import os
from dodopayments import DodoPayments

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

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

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

app = Flask(__name__)

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

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

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

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

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

API Response

All methods above return the same response structure:

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

Get the checkout URL

Extract the checkout_url from the API response.

Redirect your customer

Direct your customer to the checkout URL to complete their purchase.

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

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

Alternative Integration Options: Instead of redirecting, you can embed the checkout directly in your page using Overlay Checkout (modal overlay) or Inline Checkout (fully embedded). Both options use the same checkout session URL.

Handle the return

After payment, customers are redirected to your return_url with query parameters including payment/subscription ID, status, customer email, and any license keys. See the return_url parameter docs for the full list.

Request Body

Required Fields

Essential fields needed for every checkout session

Optional Fields

Additional configuration to customize your checkout experience

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 Dodo Payments dashboard.

Mixed Checkout: You can combine one-time payment products and subscription products in the same checkout session. This enables powerful use cases like setup fees with subscriptions, hardware bundles with SaaS, and more.

Hiện Product Cart Item Properties

product_id

string

bắt buộc

The unique identifier of the product from your Dodo Payments dashboard.Example: "prod_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 if the product is a subscription.

Hiện Addon item properties

addon_id

string

bắt buộc

quantity

integer

bắt buộc

amount

integer

Amount the customer pays if pay_what_you_want is enabled. If disabled, this field will be ignored.Định dạng: Được biểu thị bằng đơn vị nhỏ nhất của tiền tệ (ví dụ, xu đối với USD). Ví dụ, để tính phí $1.00, hãy truyền 100.

credit_entitlements

array

Ghi đè từng phiên thanh toán cho các quyền tín dụng đã được đính kèm vào sản phẩm này. Sử dụng điều này để cấp số lượng tín dụng khác cho phiên này — ví dụ, một gói khuyến mãi cấp 1.000 tín dụng API thay vì 500 mặc định của sản phẩm — mà không cần tạo một sản phẩm riêng biệt.

Mỗi credit_entitlement_id phải được đính kèm vào sản phẩm. Trường này chỉ ghi đè các credits_amount được cấp khi phiên này hoàn thành; cài đặt quyền tín dụng cấp sản phẩm (hết hạn, chuyển tiếp, v.v.) vẫn được áp dụng.

Hiện Credit entitlement override properties

credit_entitlement_id

string

bắt buộc

ID của quyền tín dụng để ghi đè. Phải được đính kèm vào sản phẩm.

credits_amount

string

bắt buộc

Số lượng tín dụng để cấp cho phiên thanh toán này, ghi đè mức credits_amount của sản phẩm. Phải lớn hơn không.

Tìm ID sản phẩm của bạn: Bạn có thể tìm thấy ID sản phẩm trong bảng điều khiển Dodo Payments dưới mục Products → View Details, hoặc bằng cách sử dụng API List Products.

Trường Tùy Chọn

Cấu hình những trường này để tùy chỉnh trải nghiệm thanh toán và thêm logic kinh doanh vào dòng thanh toán của bạn.

Customer Information

customer

object

Thông tin khách hàng. Bạn có thể đính kèm một khách hàng hiện có bằng ID của họ hoặc tạo hồ sơ khách hàng mới trong quá trình thanh toán.

Attach Existing Customer
New Customer

Đính kèm một khách hàng hiện có vào phiên thanh toán bằng ID của họ.

Hiện Existing Customer Properties

customer_id

string

bắt buộc

ID duy nhất của một khách hàng hiện có. Sử dụng điều này để đính kèm phiên thanh toán vào một khách hàng hiện có thay vì tạo mới.

Tạo hồ sơ khách hàng mới trong quá trình thanh toán.

Hiện New Customer Properties

string

bắt buộc

Địa chỉ email của khách hàng. Cần thiết khi tạo một khách hàng mới.

name

string

Tên đầy đủ của khách hàng như nó nên xuất hiện trên hóa đơn và biên lai.Ví dụ: "John Doe" hoặc "Jane Smith"

phone_number

string

Số điện thoại của khách hàng theo định dạng quốc tế. Cần thiết cho một số phương thức thanh toán và phòng chống gian lận.Định dạng: Bao gồm mã quốc gia, ví dụ, "+1234567890" cho số điện thoại ở Mỹ

billing_address

object

Thông tin địa chỉ thanh toán cho tính toán thuế chính xác, phòng chống gian lận và tuân thủ quy định.

Khi confirm được đặt thành true, tất cả các trường địa chỉ thanh toán trở nên bắt buộc để tạo phiên thành công.

Hiện Billing address object properties

street

string

Địa chỉ đường phố đầy đủ bao gồm số nhà, tên đường, và số căn hộ/nếu có.Ví dụ: "123 Main St, Apt 4B" hoặc "456 Oak Avenue"

city

string

Tên thành phố hoặc thị xã.Ví dụ: "San Francisco", "New York", "London"

state

string

Tên tiểu bang, tỉnh, hoặc vùng. Sử dụng tên đầy đủ hoặc viết tắt tiêu chuẩn.Ví dụ: "California" hoặc "CA", "Ontario" hoặc "ON"

country

string

bắt buộc

Mã quốc gia hai chữ cái ISO (ISO 3166-1 alpha-2). Trường này luôn bắt buộc khi địa chỉ thanh toán được cung cấp.Ví dụ: "US" (Hoa Kỳ), "CA" (Canada), "GB" (Vương Quốc Anh), "DE" (Đức)

Country Code Reference

Xem danh sách đầy đủ các quốc gia được hỗ trợ và mã ISO của họ

zipcode

string

Mã bưu chính, mã ZIP, hoặc tương đương tùy theo yêu cầu của quốc gia.Ví dụ: "94102" (Mỹ), "M5V 3A8" (Canada), "SW1A 1AA" (Anh)

Payment Configuration

allowed_payment_method_types

array

Kiểm soát các phương thức thanh toán nào có sẵn cho khách hàng trong quá trình thanh toán. Điều này giúp tối ưu hóa cho các thị trường hoặc yêu cầu kinh doanh cụ thể.Các tùy chọn có sẵn: credit, debit, upi_collect, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, cashapp, multibanco, bancontact_card, eps, ideal, przelewy24, paypal, sunbit

Quan trọng: Luôn bao gồm credit và debit như các tùy chọn dự phòng để ngăn ngừa thất bại thanh toán khi các phương thức thanh toán ưa thích không khả dụng.

Ví dụ:

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

billing_currency

string

Ghi đè lựa chọn tiền tệ mặc định với một loại tiền tệ thanh toán cố định. Sử dụng mã tiền tệ ISO 4217.Các loại tiền tệ được hỗ trợ: USD, EUR, GBP, CAD, AUD, INR, và nhiều hơnVí dụ: "USD" cho USD, "EUR" cho Euro

Trường này chỉ có hiệu quả khi giá chỉ định là bật. Nếu giá chỉ định bị tắt, tiền tệ mặc định của sản phẩm sẽ được sử dụng.

show_saved_payment_methods

boolean

mặc định:"false"

Hiển thị các phương thức thanh toán đã lưu trước đó cho khách hàng trở lại, cải thiện tốc độ thanh toán và trải nghiệm người dùng.

Session Management

return_url

string

URL để chuyển hướng khách hàng sau khi hoàn tất thanh toán. Dodo Payments thêm các tham số truy vấn sau vào URL của bạn khi chuyển hướng:

Tham số	Kiểu	Điều kiện
`payment_id`	`string`	Luôn có mặt cho các khoản thanh toán một lần
`subscription_id`	`string`	Luôn có mặt cho các khoản thanh toán đăng ký
`status`	`string`	Luôn có mặt
`license_key`	`string`	Có mặt nếu sản phẩm có kích hoạt mã giấy phép. Phân tách bằng dấu phẩy nếu có nhiều khóa
`email`	`string`	Có mặt nếu khách hàng có email được lưu theo dữ liệu

Ví dụ URL chuyển hướng:

# 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

Sử dụng các tham số truy vấn license_key và email để hiển thị các khóa giấy phép hoặc gửi xác nhận ngay lập tức trên trang trở về của bạn, mà không cần một cuộc gọi API bổ sung.

cancel_url

string

URL để chuyển hướng khách hàng khi họ nhấn nút quay lại hoặc hủy bỏ phiên thanh toán. Nếu không được cung cấp, nút quay lại sẽ không được hiển thị.

Đặt cancel_url để cung cấp cho khách hàng một cách rõ ràng để trở lại trang web của bạn mà không hoàn tất mua hàng. Điều này cải thiện trải nghiệm thanh toán và giảm ma sát.

confirm

boolean

mặc định:"false"

Nếu đúng, hoàn tất tất cả các chi tiết phiên ngay lập tức. API sẽ ném ra lỗi nếu dữ liệu cần thiết bị thiếu.

discount_codes

array

Áp dụng một hoặc nhiều mã giảm giá xếp chồng vào phiên thanh toán. Mã được áp dụng theo thứ tự mảng (mã đầu tiên giảm giá gốc, mã thứ hai giảm giá một mức đã giảm trước đó, và như vậy), lên đến mức tối đa 20 mã mỗi phiên.

discount_codes: ['WELCOME10', 'BLACKFRIDAY20']

Trường discount_code đơn số dưới đây là ngừng sử dụng nhưng vẫn đang được hỗ trợ đầy đủ — các tích hợp hiện có vẫn hoạt động mà không cần thay đổi. Không thể kết hợp với discount_codes trong cùng một yêu cầu. Chuyển sang discount_codes khi thuận tiện để tận dụng việc xếp chồng.

discount_code

string

không còn sử dụng

Ngừng sử dụng — ưu tiên discount_codes cho các tích hợp mới. Trường này vẫn hoạt động nhằm đảm bảo khả năng tương thích ngược, nhưng không thể kết hợp với discount_codes trong cùng một yêu cầu.

metadata

object

Cặp khóa-giá trị tùy chỉnh để lưu trữ thông tin bổ sung về phiên.

force_3ds

boolean

Ghi đè hành vi mặc định 3DS của thương gia cho phiên này.

minimal_address

boolean

mặc định:"false"

Kích hoạt chế độ thu thập địa chỉ tối thiểu. Khi bật, thanh toán chỉ thu thập:

Quốc gia: Luôn yêu cầu để xác định thuế
Mã bưu chính/Postal code: Chỉ ở các khu vực cần thiết để tính thuế bán hàng, VAT hoặc GST

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

Kích hoạt địa chỉ tối thiểu để hoàn thành thanh toán nhanh hơn. Thu thập địa chỉ đầy đủ vẫn có sẵn cho các doanh nghiệp yêu cầu đầy đủ chi tiết thanh toán.

UI Customization & Features

customization

object

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

Hiện Customization object properties

theme

string

mặc định:"system"

Chủ đề cho giao diện thanh toán. Các tùy chọn: light, dark, hoặc system.

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ẻ “theo yêu cầu” cho các sản phẩm áp dụng.

force_language

string

Bắt 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ữ trình duyệt của khách hàng.Mã ngôn ngữ hỗ trợ: ar (Ả Rập), ca (Catalan), de (Đức), en (Anh), es (Tây Ban Nha), fr (Pháp), he (Hebrew), id (Indonesia), it (Ý), ja (Nhật Bản), ko (Hàn Quốc), ms (Malay), nl (Hà Lan), pl (Ba Lan), pt (Bồ Đào Nha), ro (Romania), ru (Nga), sv (Thụy Điển), th (Thái Lan), tr (Thổ Nhĩ Kỳ), zh (Trung Quốc)Ví dụ: "es" cho Tây Ban Nha, "ja" cho Nhật Bản

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 object properties

allow_currency_selection

boolean

mặc định:"true"

Cho phép khách hàng chọn tiền tệ ưa thích của họ 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 khách hàng thêm hoặc xóa addons trên sản phẩm đăng ký trong quá trình thanh toán. Chỉ áp dụng cho các 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 khách hàng trong quá trình thanh toán.

allow_tax_id

boolean

mặc định:"true"

Cho phép khách hàng nhập số nhận dạng thuế.

always_create_new_customer

boolean

mặc định:"false"

Buộc tạo một hồ sơ khách hàng mới thay vì cập nhật các hồ sơ hiện có.

allow_customer_editing_email

boolean

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

allow_customer_editing_name

boolean

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

allow_customer_editing_street

boolean

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

allow_customer_editing_city

boolean

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

allow_customer_editing_state

boolean

Cho phép khách hàng chỉnh sửa tiểu bang trong quá trình thanh toán.

allow_customer_editing_country

boolean

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

allow_customer_editing_zipcode

boolean

Cho phép khách hàng chỉnh sửa mã bưu điện trong quá trình thanh toán.

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 khách hàng ngay lập tức tới return_url sau khi hoàn tất thanh toán.

Sử dụng điều này khi bạn có một 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 các ứng dụng di động và các quy trình thanh toán tích hợp.

Custom Fields

custom_fields

array

Thu thập thông tin bổ sung từ khách hàng trong quá trình thanh toán với các trường tùy chỉnh. Bạn có thể định nghĩa tối đa 5 trường tùy chỉnh cho mỗi phiên thanh toán. Phản hồi của khách hàng sẽ được bao gồm trong payload của webhook và có sẵn qua API.

Hiện Custom field object properties

key

string

bắt buộc

Điểm định danh duy nhất cho trường này. Được sử dụng làm khóa trong payload của webhook và phản hồi API.Example: "company_name", "referral_source", "team_size"

label

string

bắt buộc

Nhãn hiển thị được hiển thị cho khách hàng trên biểu mẫu thanh toán.Example: "Company Name", "How did you hear about us?", "Team Size"

field_type

string

bắt buộc

Loại trường xác định quy tắc xác thực đầu vào.Available types:

text - Đầu vào văn bản một dòng
number - Đầu vào số
email - Địa chỉ email với xác thực
url - URL với xác thực
date - Bộ chọn ngày
dropdown - Chọn từ các tùy chọn đã định sẵn
boolean - Chuyển đổi Có/Không

required

boolean

mặc định:"false"

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

placeholder

string

Văn bản giữ chỗ hiển thị trong trường đầu vào.

options

array

Danh sách các tùy chọn cho loại trường dropdown. Yêu cầu khi field_type là dropdown, bị bỏ qua cho các loại khác.Example: ["Google", "Twitter", "Friend referral", "Other"]

Phản hồi của khách hàng với các trường tùy chỉnh được bao gồm trong:

Webhooks: payment.succeeded, subscription.active, và các payload sự kiện liên quan khác chứa mảng custom_field_responses
API responses: Các đối tượng thanh toán và đăng ký 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 các sản phẩm đăng ký.

Hiện Subscription data object properties

trial_period_days

integer

Số ngày cho thời gian dùng thử trước khi tính phí lần đầu. Phải từ 0 đến 10000 ngày.

on_demand

object

Cấu hình đăng ký theo nhu cầu cho thanh toán theo mức sử dụng hoặc đo lường.

Hiện On-demand object properties

mandate_only

boolean

bắt buộc

Nếu đặt thành true, sẽ không thực hiện bất kỳ khoản phí nào và 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 lần tính phí ban đầu đối với khách hàng. Nếu không chỉ định, giá đã lưu trữ của sản phẩm sẽ được sử dụng.Format: Được biểu diễn dưới đơn vị thấp nhất của tiền tệ (ví dụ: xu đối với USD). Ví dụ, để tính phí $1.00, hãy truyền 100.

product_currency

string

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

product_description

string

Ghi đè mô tả sản phẩm tùy chọn cho hóa đơn và các mặt hàng. Nếu không chỉ định, mô tả đã lưu trữ của sản phẩm sẽ được sử dụng.

adaptive_currency_fees_inclusive

boolean

Có bao gồm phí tiền tệ thích ứng trong giá sản phẩm (true) hay thêm lên trên (false). Bỏ qua nếu định giá thích ứng không được bật.

Ví dụ Sử dụng

Dưới đây là 10 ví dụ toàn diện trình bày các cấu hình phiên thanh toán khác nhau cho các kịch bản kinh doanh khác nhau:

1. Thanh toán Đơn giản với Sản phẩm Đơn lẻ

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

2. Giỏ hàng Nhiều Sản phẩm

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

3. Đăng ký với Thời gian Dùng thử

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

4. Thanh toán đã được Xác nhận Trước

Khi confirm được đặt thành true, khách hàng sẽ được chuyển trực tiếp đến trang thanh toán, bỏ qua các bước xác nhận.

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

5. Thanh toán với Ghi đè Đơn vị tiền tệ

Mục billing_currency chỉ có hiệu lực khi đơn vị tiền tệ thích ứng được bật trong cài đặt tài khoản của bạn. Nếu đơn vị tiền tệ thích ứng bị tắt, tham số này sẽ không có hiệu lực.

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

6. Các Phương thức Thanh toán Lưu cho Khách hàng Quay lại

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

7. Thanh toán B2B với Thu thập ID Thuế

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

8. Thanh toán Chủ đề Tối với Mã Giảm giá Xếp chồng

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

9. Phương thức Thanh toán Khu vực (UPI cho Ấn Độ)

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

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

10. 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 tra BNPL, hãy xem trang Mua Trước Trả Sau (BNPL).

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

11. Sử dụng Phương thức Thanh toán Hiện có cho Thanh toán Ngay lập tức

Sử dụng phương thức thanh toán đã lưu của khách hàng để tạo phiên thanh toán xử lý ngay lập tức, bỏ qua thu thập phương thức thanh toán:

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

Khi sử dụng payment_method_id, confirm phải được đặt thành true và một customer_id hiện có phải được cung cấp. Phương thức thanh toán sẽ được xác thực về tính hợp lệ với đơn vị tiền tệ thanh toán.

Phương thức thanh toán phải thuộc về khách hàng và tương thích với đơn vị tiền tệ thanh toán. Điều này cho phép mua hàng chỉ với một cú nhấp chuột cho khách hàng quay lại.

12. Liên kết Ngắn gọn cho URL Thanh toán Sạch hơn

Tạo các liên kết thanh toán ngắn hơn, có thể chia sẻ với các slug tùy chỉnh:

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

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

Liên kết ngắn hoàn hảo cho việc chia sẻ qua SMS, email hoặc mạng xã hội. Chúng dễ nhớ hơn và tạo lòng tin cho khách hàng hơn so với các URL dài.

13. Bỏ Qua Trang Thành công Thanh Toán với Chuyển hướng Ngay lập tức

Chuyển hướng khách hàng ngay lập tức sau khi hoàn tất thanh toán, bỏ qua trang thành công mặc định:

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

Sử dụng redirect_immediately: true khi bạn có một trang thành công tùy chỉnh cung cấp trải nghiệm người dùng tốt hơn trang thành công thanh toán mặc định. Điều này đặc biệt hữu ích cho ứng dụng di động và luồng thanh toán tích hợp.

Khi redirect_immediately được bật, khách hàng sẽ được chuyển hướng đến return_url của bạn ngay sau khi hoàn tất thanh toán, bỏ qua toàn bộ trang thành công mặc định.

14. Buộc Sử dụng Ngôn ngữ

Buộc hiển thị thanh toán bằng ngôn ngữ cụ thể, ghi đè việc phát hiện ngôn ngữ của trình duyệt khách hàng:

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

Sử dụng force_language khi bạn biết ngôn ngữ ưu tiên của khách hàng (ví dụ, từ cài đặt tài khoản của họ) hoặc khi nhắm mục tiêu vào các thị trường khu vực cụ thể.

Supported languages: tiếng Ả Rập (ar), tiếng Catalan (ca), tiếng Trung (zh), tiếng Hà Lan (nl), tiếng Anh (en), tiếng Pháp (fr), tiếng Đức (de), tiếng Hebrew (he), tiếng Indonesia (id), tiếng Ý (it), tiếng Nhật (ja), tiếng Hàn (ko), tiếng Mã Lai (ms), tiếng Ba Lan (pl), tiếng Bồ Đào Nha (pt), tiếng Romania (ro), tiếng Nga (ru), tiếng Tây Ban Nha (es), tiếng Thụy Điển (sv), tiếng Thái (th), tiếng Thổ Nhĩ Kỳ (tr)

15. Thu thập Trường Tùy chỉnh

Thu thập thông tin bổ sung từ khách hàng trong quá trình thanh toán bằng cách sử dụng các trường tùy chỉnh:

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

Phản hồi trường tùy chỉnh được tự động bao gồm trong payload của webhook (payment.succeeded, subscription.active, v.v.) và có thể được truy xuất qua API. Sử dụng chúng để làm giàu CRM của bạn, kích hoạt luồng onboarding hoặc tùy chỉnh trải nghiệm khách hàng.

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

Xem trước Các Phiên Thanh toán

Trước khi tạo một phiên thanh toán, bạn có thể xem trước phân tích giá cả bao gồm thuế, giảm giá và tổng số. Điều này hữu ích cho việc hiển thị giá cả chính xác cho khách hàng trước khi họ tiến hành thanh toán.

Node.js SDK
Python SDK

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

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

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

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

Preview API Reference

Xem toàn bộ tài liệu về endpoint xem trước.

Di chuyển từ Liên kết Động đến Phiên Thanh toán

Khác biệt Chính

Trước đây, khi tạo một liên kết thanh toán với Liên kết Động, bạn phải cung cấp địa chỉ thanh toán đầy đủ của khách hàng. Với Phiên Thanh toán, điều này không còn cần thiết nữa. Bạn chỉ cần truyền thông tin bạn có, và chúng tôi sẽ xử lý phần còn lại. Ví dụ:

Nếu bạn chỉ biết quốc gia thanh toán của khách hàng, chỉ cần cung cấp điều đó.
Quy trình thanh toán sẽ tự động thu thập các chi tiết còn thiếu trước khi chuyển khách hàng đến trang thanh toán.
Mặt khác, nếu bạn đã có tất cả thông tin yêu cầu và muốn bỏ qua trực tiếp đến trang thanh toán, bạn có thể truyền toàn bộ dữ liệu và bao gồm confirm=true trong yêu cầu của bạn.

Quá trình Di chuyển

Di chuyển từ Liên kết Động sang Phiên Thanh toán rất đơn giản:

Update your integration

Cập nhật tích hợp của bạn để sử dụng phương pháp API hoặc SDK mới.

Adjust request payload

Điều chỉnh payload yêu cầu theo định dạng Phiên Thanh toán.

That's it!

Có. Không cần xử lý thêm hay các bước di chuyển đặc biệt nào từ phía bạn.

Tham khảo API liên quan

Create Checkout Session

Tham khảo API đầy đủ để tạo các phiên thanh toán với tất cả các tham số và tùy chọn có sẵn

Preview Checkout Session

Tham khảo API để xem trước giá cả, thuế và tổng số trước khi tạo một phiên

Lần sửa đổi cuối 9 tháng 7, 2026

Thanh Toán Giá ĐộngTạo các liên kết thanh toán linh hoạt với giá biến đổi bằng cách sử dụng một sản phẩm duy nhất. Bật Pay What You Want để cho phép khách hàng chọn giá của họ hoặc thiết lập các khoản tiền động một cách lập trình.

Quick Start Guide

API Reference & Live Testing

Preview Checkout

​Prerequisites

​Creating Your First Checkout Session

​API Response

​Request Body

Required Fields

Optional Fields

​Required Fields

​Trường Tùy Chọn

Country Code Reference

​Ví dụ Sử dụng

​1. Thanh toán Đơn giản với Sản phẩm Đơn lẻ

​2. Giỏ hàng Nhiều Sản phẩm

​3. Đăng ký với Thời gian Dùng thử

​4. Thanh toán đã được Xác nhận Trước

​5. Thanh toán với Ghi đè Đơn vị tiền tệ

​6. Các Phương thức Thanh toán Lưu cho Khách hàng Quay lại

​7. Thanh toán B2B với Thu thập ID Thuế

​8. Thanh toán Chủ đề Tối với Mã Giảm giá Xếp chồng

​9. Phương thức Thanh toán Khu vực (UPI cho Ấn Độ)

​10. Thanh toán BNPL (Mua Trước Trả Sau)

​11. Sử dụng Phương thức Thanh toán Hiện có cho Thanh toán Ngay lập tức

​12. Liên kết Ngắn gọn cho URL Thanh toán Sạch hơn

​13. Bỏ Qua Trang Thành công Thanh Toán với Chuyển hướng Ngay lập tức

​14. Buộc Sử dụng Ngôn ngữ

​15. Thu thập Trường Tùy chỉnh

​Xem trước Các Phiên Thanh toán

Preview API Reference

​Di chuyển từ Liên kết Động đến Phiên Thanh toán

​Khác biệt Chính

​Quá trình Di chuyển

​Tham khảo API liên quan

Create Checkout Session

Preview Checkout Session

Prerequisites

Creating Your First Checkout Session

API Response

Request Body

Required Fields

Trường Tùy Chọn

Ví dụ Sử dụng

1. Thanh toán Đơn giản với Sản phẩm Đơn lẻ

2. Giỏ hàng Nhiều Sản phẩm

3. Đăng ký với Thời gian Dùng thử

4. Thanh toán đã được Xác nhận Trước

5. Thanh toán với Ghi đè Đơn vị tiền tệ

6. Các Phương thức Thanh toán Lưu cho Khách hàng Quay lại

7. Thanh toán B2B với Thu thập ID Thuế

8. Thanh toán Chủ đề Tối với Mã Giảm giá Xếp chồng

9. Phương thức Thanh toán Khu vực (UPI cho Ấn Độ)

10. Thanh toán BNPL (Mua Trước Trả Sau)

11. Sử dụng Phương thức Thanh toán Hiện có cho Thanh toán Ngay lập tức

12. Liên kết Ngắn gọn cho URL Thanh toán Sạch hơn

13. Bỏ Qua Trang Thành công Thanh Toán với Chuyển hướng Ngay lập tức

14. Buộc Sử dụng Ngôn ngữ

15. Thu thập Trường Tùy chỉnh

Xem trước Các Phiên Thanh toán

Di chuyển từ Liên kết Động đến Phiên Thanh toán

Khác biệt Chính

Quá trình Di chuyển

Tham khảo API liên quan