Checkout Sessions

Create secure, hosted checkout experiences that handle the complete payment flow for both one-time purchases and subscriptions with full customization control.

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

1. Dodo Payments Account

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

2. API Credentials

   Generate your API credentials from the Dodo Payments dashboard:

3. Products Setup

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

​

Creating Your First Checkout Session

Node.js SDK

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

Python SDK

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

REST API

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

1. Get the checkout URL

   Extract the checkout_url from the API response.

2. 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.

3. 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

Đí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.

New Customer

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

Hiện New Customer Properties

email · 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ụ, "[phone]" 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ơn

Ví 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_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"

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

allow_customer_editing_email · boolean

Cho phép khách hàng chỉnh sửa địa chỉ email của họ 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 của họ 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 chính trong quá trình thanh toán.

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 cho việc xác định thuế
• Mã bưu chính/Postal code: Chỉ ở những vùng mà nó 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 cần đầy đủ chi tiết 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 đến trang return_url của bạn 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à luồng thanh toán nhúng.

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 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 khách hàng được bao gồm trong tải trọng webhook và có sẵn qua API.

Hiện Custom field object properties

key · string · bắt buộc

ID duy nhất cho trường này. Sử dụng như khóa trong các tải trọng webhook và phản hồi API.

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

label · string · bắt buộc

Nhãn hiển thị cho thấy khách hàng trên 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 quy tắc xác nhận đầu vào.

Các loại có sẵn:

• text - Đầu vào văn bản dòng đơn
• number - Đầu vào số
• email - Địa chỉ email có xác nhận
• url - URL có xác nhận
• date - Chọn ngày
• dropdown - Chọn từ các tùy chọn được xác định trước
• boolean - Chuyển đổi Có/Không

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

Liệu trường này có cần phải được điền trước khi thanh toán có thể hoàn thành.

placeholder · string

Văn bản giữ chỗ hiển thị trong trường nhập liệu.

options · array

Danh sách các tùy chọn cho loại trường dropdown. Cần thiết khi field_type là dropdown, bỏ qua cho các loại khác.

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

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

• Webhooks: payment.succeeded, subscription.active, và các tải sự kiện liên quan khác chứa mảng custom_field_responses
• Phản hồi API: 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 sản phẩm đăng ký.

Hiện Subscription data object properties

trial_period_days · integer

Số ngày cho thời gian thử nghiệm trước khi tính phí đầu tiên. Phải nằm trong khoảng từ 0 đến 10.000 ngày.

on_demand · object

Cấu hình đăng ký theo yêu cầu cho thanh toán dựa trên sử dụng hoặc đo đạc.

Hiện On-demand object properties

mandate_only · boolean · bắt buộc

Nếu được đặt là đúng, không thực hiện bất kỳ khoản phí nào và chỉ xác thực 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 đố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.

Đị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.

product_currency · string

Tiền tệ tùy chọn của giá sản phẩm. Nếu không 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 được ghi đè cho hóa đơn và mục 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

Liệu phí tiền tệ đa dạng có nên được bao gồm trong giá sản phẩm (true) hay thêm bên ngoài (false). Bỏ qua nếu giá chỉ định không được bật.

​

Ví dụ Sử Dụng

Dưới đây là 10 ví dụ toàn diện minh họa các cấu hình phiên thanh toán khác nhau cho các tình huống kinh doanh khác nhau:

​

1. Thanh Toán Sản Phẩm Đơn Giản

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

​

2. Giỏ Hàng Đa 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: '[e-mail]',
    name: 'John Doe',
    phone_number: '[phone]'
  },
  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 Thử Nghiệm

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_plan',
      quantity: 1
    }
  ],
  subscription_data: {
    trial_period_days: 14
  },
  customer: {
    email: '[e-mail]',
    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 đưa trực tiếp tới trang thanh toán, bỏ qua bất kỳ bước xác nhận nào.

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_premium_course',
      quantity: 1
    }
  ],
  customer: {
    email: '[e-mail]',
    name: 'Alex Johnson',
    phone_number: '[phone]'
  },
  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 Đè Tiền Tệ

Ghi đè billing_currency chỉ có hiệu quả khi tiền tệ đa dạng được bật trong cài đặt tài khoản của bạn. Nếu tiền tệ đa dạng bị tắt, tham số này sẽ không có tác dụng.

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_consulting_service',
      quantity: 1
    }
  ],
  customer: {
    email: '[e-mail]',
    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. Phương Thức Thanh Toán Đã Lưu cho Khách Hàng Trở Lại

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_monthly_subscription',
      quantity: 1
    }
  ],
  customer: {
    email: '[e-mail]',
    name: 'Robert Johnson',
    phone_number: '[phone]'
  },
  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 Mã Số Thuế

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_enterprise_license',
      quantity: 5
    }
  ],
  customer: {
    email: '[e-mail]',
    name: 'Sarah Davis',
    phone_number: '[phone]'
  },
  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: '[e-mail]'
  }
});

​

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: '[e-mail]',
    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êm thông tin chi tiết về cấu hình và thử nghiệm 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: '[e-mail]',
    name: 'Priya Sharma',
    phone_number: '[phone]'
  },
  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êm thông tin chi tiết về cấu hình và thử nghiệm 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: '[e-mail]',
    name: 'Emma Thompson',
    phone_number: '[phone]'
  },
  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 một phiên thanh toán được xử lý ngay lập tức, bỏ qua việc 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à phải cung cấp customer_id hiện có. Phương thức thanh toán sẽ được xác thực cho đủ điều kiện với đơn vị tiền tệ của thanh toán.

Phương thức thanh toán phải thuộc về khách hàng và phù hợp với đơn vị tiền tệ của thanh toán. Điều này cho phép các giao dịch mua chỉ cần nhấp một lần cho khách hàng trở lại.

​

12. Liên Kết Ngắn cho URL Thanh Toán Gọn Gàng Hơn

Tạo các liên kết thanh toán rút gọn, có thể chia sẻ với đoạn đường dẫn 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: '[e-mail]',
    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

Các liên kết ngắn rất phù hợp cho SMS, email, hoặc chia sẻ trên mạng xã hội. Chúng dễ nhớ hơn và xây dựng lòng tin của khách hàng tốt hơn so với 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: '[e-mail]',
    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 so với trang thành công thanh toán mặc định. Điều này đặc biệt hữu ích cho các ứng dụng di động và luồng thanh toán nhúng.

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

​

14. Ép Buộc Một Ngôn Ngữ

Bắt buộc thanh toán hiển thị bằng một ngôn ngữ cụ thể, ghi đè phát hiện ngôn ngữ trình duyệt của 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: '[e-mail]',
    name: 'Tanaka Yuki'
  },
  return_url: 'https://yourapp.com/success'
});

Sử dụng force_language khi bạn biết ngôn ngữ ưa thích 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ể.

Ngôn ngữ hỗ trợ: 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 Bản (ja), Tiếng Hàn Quốc (ko), Tiếng Malay (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 Các 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á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: '[e-mail]',
    name: 'Jane Doe'
  },
  return_url: 'https://yourapp.com/success'
});

Các phản hồi của khách hàng đối với các trường tùy chỉnh được tự động bao gồm trong tải hoạt động 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 phong phú thêm 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.

Loại trường có sẵn: text, number, email, url, date, dropdown, boolean

​

Xem Trướ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 sự phân chia giá bao gồm cả thuế, giảm giá, và tổng số. Điều này hữu ích cho việc hiển thị giá chính xác cho khách hàng trước khi họ tiến hành thanh toán.

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

Python SDK

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 tài liệu đầy đủ điểm cuối xem trước.

​

Di Chuyển Từ Liên Kết Động Sang Phiên Thanh Toán

​

Sự 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 cần 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 chuyển qua bất kỳ thông tin nào 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 đó.
• Dòng 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 tới trang thanh toán.
• Mặt khác, nếu bạn đã có tất cả các thông tin cần thiết và muốn bỏ qua trực tiếp tới trang thanh toán, bạn có thể truyền đầy đủ dữ liệu và bao gồm confirm=true trong nội dung 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:

1. 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.

2. Adjust request payload

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

3. That's it!

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

​

Tham Chiếu API Liên Quan

Create Checkout Session

Tham chiếu API đầy đủ để tạo 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 chiếu API để xem trước giá, thuế, và tổng số trước khi tạo một phiên