Checkout Sessions

Quick Start Guide

Get your first checkout session running in under 5 minutes

API Reference & Live Testing

Explore the full API documentation and interactively test Checkout Session requests and responses.

Preview Checkout

Calculate pricing, taxes, and totals before creating a session.

Session Validity: Checkout sessions are valid for 24 hours by default. If you pass confirm=true in your request, the session will only be valid for 15 minutes.

Single-Use Links: The checkout_url returned by the API is not reusable and expires within 24 hours (or 15 minutes when confirm=true). It is intended for a single customer to complete one payment. Generate a fresh checkout session for each customer and each payment attempt rather than sharing or reusing a link.

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: 'pdt_123', // Replace with your actual product ID
          quantity: 1
        }
      ],
      
      // Pre-fill customer information to reduce friction
      customer: {
        email: 'customer@example.com',
        name: 'John Doe',
        phone_number: '+1234567890'
      },
      
      // Billing address for tax calculation and compliance
      billing_address: {
        street: '123 Main St',
        city: 'San Francisco',
        state: 'CA',
        country: 'US', // Required: ISO 3166-1 alpha-2 country code
        zipcode: '94102'
      },
      
      // Where to redirect after successful payment
      return_url: 'https://yoursite.com/checkout/success',
      
      // Custom data for your internal tracking
      metadata: {
        order_id: 'order_123',
        source: 'web_app'
      }
    });

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

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

import os
from dodopayments import DodoPayments

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

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

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

app = Flask(__name__)

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

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

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

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

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

API Response

All methods above return the same response structure:

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

Only session_id is guaranteed to be present. Two cases return additional or fewer fields:

payment_method_id was provided — the charge is processed immediately and checkout_url is null. Use the returned payment_id instead.
confirm: true created the payment at session-creation time — the response also includes payment_id, client_secret, and publishable_key for use with the Dodo Payments checkout SDK.

The generated checkout_url is single-use and expires within 24 hours. Don’t cache or reuse it across customers or payment attempts — create a new checkout session whenever you need a fresh link.

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). In a native mobile app, hand the same URL to the Mobile Checkout SDKs for Android, iOS, React Native, or Flutter. All of these consume 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

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

string

bắt buộc

The unique identifier of the product from your Dodo Payments dashboard.Ví dụ: "pdt_123abc456def"

integer

bắt buộc

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

array

Array of addons to attach to the product. Only valid if the product is a subscription.

Hiện Addon item properties

string

bắt buộc

integer

bắt buộc

integer

Amount the customer pays if pay_what_you_want is enabled. If disabled, this field will be ignored.Format: Represented in the lowest denomination of the currency (e.g., cents for USD). For example, to charge $1.00, pass 100.

array

Per-checkout-session overrides for credit entitlements already attached to this product. Use this to grant a different number of credits for this single session — e.g., a promotional bundle that grants 1,000 API credits instead of the product-default 500 — 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

string

bắt buộc

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

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

Configure these fields to customize the checkout experience and add business logic to your payment flow.

Customer Information

object

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

Attach Existing Customer
New Customer

Attach an existing customer to the checkout session using their ID.

Hiện Existing Customer Properties

string

bắt buộc

The unique identifier of an existing customer. Use this to attach the checkout session to an existing customer instead of creating a new one.

Create a new customer record during checkout.

Hiện New Customer Properties

string

bắt buộc

Customer’s email address. Required when creating a new customer.

string

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

string

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

object

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

When confirm is set to true, all billing address fields become required for successful session creation.

Hiện Billing address object properties

string

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

string

City or municipality name.Example: "San Francisco", "New York", "London"

string

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

string

bắt buộc

Two-letter ISO country code (ISO 3166-1 alpha-2). This field is always required when billing_address is provided.Examples: "US" (United States), "CA" (Canada), "GB" (United Kingdom), "DE" (Germany)

Country Code Reference

View complete list of supported countries and their ISO codes

string

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

Payment Configuration

array

Control which payment methods are available to customers during checkout. This helps optimize for specific markets or business requirements.Các tùy chọn phổ biến: credit, debit, upi_collect, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, cashapp, ach, multibanco, bancontact_card, eps, ideal, blik, paypal. Đây không phải là toàn bộ tập giá trị — hãy xem tài liệu tham khảo API Create Checkout Session để biết mọi giá trị được chấp nhận.

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

Example:

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

string

Override the default currency selection with a fixed billing currency. Uses ISO 4217 currency codes.Supported Currencies: USD, EUR, GBP, CAD, AUD, INR, and moreExample: "USD" for US Dollars, "EUR" for Euros

This field is only effective when adaptive pricing is enabled. If adaptive pricing is disabled, the product’s default currency will be used.

boolean

mặc định:"false"

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

Session Management

string

URL to redirect customers after payment completion. Dodo Payments appends the following query parameters to your URL on redirect:

Parameter	Type	Condition
`payment_id`	`string`	Always present for one-time payments
`subscription_id`	`string`	Always present for subscription payments
`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 URLs:

# One-time payment with license key
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com

# Subscription payment with multiple license keys
https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001,LK-002&email=customer%40example.com

# Payment without license keys
https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&email=customer%40example.com

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

string

URL to redirect customers when they click the back button or cancel the checkout session. If not provided, the back button will not be displayed.

Set a cancel_url to give customers a clear way to return to your site without completing the purchase. This improves the checkout experience and reduces friction.

boolean

mặc định:"false"

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

array

Áp dụng một hoặc nhiều mã giảm giá xếp chồng cho phiên thanh toán. Các mã được áp dụng theo thứ tự trong mảng (mã đầu tiên giảm giá khởi điểm, mã thứ hai giảm giá đã được giảm, và tiếp tục như vậy), tối đa 20 mã cho mỗi phiên. Khi Purchasing Power Parity được bật, giá khởi điểm là số tiền đã điều chỉnh theo PPP, không phải giá cơ sở.

discount_codes: ['WELCOME10', 'BLACKFRIDAY20']

The singular discount_code field below is deprecated but still fully supported — existing integrations continue to work without changes. It cannot be combined with discount_codes in the same request. Migrate to discount_codes when convenient to take advantage of stacking.

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.

object

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

boolean

Override merchant default 3DS behaviour for this session.

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

This significantly reduces checkout friction by eliminating unnecessary form fields.

Enable minimal address for faster checkout completion. Full address collection remains available for businesses that require complete billing details.

string

A saved payment method belonging to the attached customer. Requires confirm: true and an existing customer.customer_id. When set, the charge is processed immediately and checkout_url is returned as null — use the returned payment_id instead.

boolean

mặc định:"false"

If true, returns a shortened checkout URL instead of the full session URL.

string

Product collection ID for the collection-based checkout flow.

string

Tax ID for the customer (for example, a VAT number). Requires billing_address with a country.

string

Optional business or legal name associated with the tax ID. When provided together with a valid tax_id, it is rendered on the invoice instead of the customer’s personal name.

integer

Override the merchant-level mandate floor (in INR paise) for INR e-mandates on Indian cards.

UI Customization & Features

object

Customize the appearance and behavior of the checkout interface.

Hiện Customization object properties

string

mặc định:"system"

Theme for the checkout interface. Options: light, dark, or system.

boolean

mặc định:"true"

Display order details section in the checkout interface.

boolean

mặc định:"true"

Show the “on-demand” tag for applicable products.

string

Force the checkout interface to render in a specific language. By default, the checkout auto-detects the customer’s browser language.Supported language codes: ar (Arabic), ca (Catalan), de (German), en (English), es (Spanish), fr (French), he (Hebrew), id (Indonesian), it (Italian), ja (Japanese), ko (Korean), ms (Malay), nl (Dutch), pl (Polish), pt (Portuguese), ro (Romanian), ru (Russian), sv (Swedish), th (Thai), tr (Turkish), zh (Chinese)Example: "es" for Spanish, "ja" for Japanese

object

Custom theme configuration with colors for light and dark modes, fonts, and button styling. This is the server-side replacement for the deprecated client-side themeConfig option.

Hiện Theme config properties

object

Light mode color configuration.

object

Dark mode color configuration.

string

URL for the primary font. Must be a valid https:// URL.

string

URL for the secondary font. Must be a valid https:// URL.

string

Font size for the checkout UI. Options: xs, sm, md, lg, xl, 2xl.

string

Font weight for the checkout UI. Options: normal, medium, bold, extraBold.

string

Custom text for the pay button (for example, "Complete Purchase" or "Subscribe Now"). Max 100 characters.

string

Border radius for UI elements. A number followed by px, rem, or em (for example, "4px", "0.5rem", "1em").

object

Configure specific features and behaviors for the checkout session.

Hiện Feature flags object properties

boolean

mặc định:"true"

Allow customers to select their preferred currency during checkout.

boolean

mặc định:"true"

Show discount code input field in the checkout interface.

boolean

mặc định:"false"

Allow customers to add or remove addons on a subscription product during checkout. Only applies to subscription products.

boolean

mặc định:"true"

Collect customer phone numbers during checkout.

boolean

mặc định:"false"

Require the customer to provide a phone number to complete checkout. Requires allow_phone_number_collection to also be true.

boolean

mặc định:"true"

Allow customers to enter tax identification numbers.

boolean

mặc định:"false"

Force creation of a new customer record instead of updating existing ones.

boolean

Allow customers to edit their email address during checkout.

boolean

Allow customers to edit their name during checkout.

boolean

Allow customers to edit the street address during checkout.

boolean

Allow customers to edit the city during checkout.

boolean

Allow customers to edit the state during checkout.

boolean

Allow customers to edit the country during checkout.

boolean

Allow customers to edit the zipcode during checkout.

boolean

Allow customers to enter or edit their tax ID during checkout.

boolean

mặc định:"false"

Allow the customer to supply or edit the business name associated with the tax ID. Works independently of allow_customer_editing_tax_id — either flag (or allow_tax_id) is sufficient. Typically set together with allow_customer_editing_tax_id.

boolean

mặc định:"false"

Skip the default payment success page and redirect customers immediately to your return_url after payment completion.

Use this when you have a custom success page that provides a better user experience, or for mobile apps and embedded checkout flows.

Custom Fields

array

Collect additional information from customers during checkout with custom form fields. You can define up to 5 custom fields per checkout session. Customer responses are included in webhook payloads and available via the API.

Hiện Custom field object properties

string

bắt buộc

Unique identifier for this field. Used as the key in webhook payloads and API responses.Example: "company_name", "referral_source", "team_size"

string

bắt buộc

Display label shown to the customer on the checkout form.Example: "Company Name", "How did you hear about us?", "Team Size"

string

bắt buộc

Type of field determining input validation rules.Available types:

text - Single-line text input
number - Numeric input
email - Email address with validation
url - URL with validation
date - Date picker
dropdown - Select from predefined options
boolean - Yes/No toggle

boolean

mặc định:"false"

Whether this field must be filled before checkout can complete.

string

Placeholder text displayed in the input field.

array

List of options for dropdown field type. Required when field_type is dropdown, ignored for other types.Example: ["Google", "Twitter", "Friend referral", "Other"]

Customer responses to custom fields are included in:

Webhooks: payment.succeeded, subscription.active, and other relevant event payloads contain the custom_field_responses array
API responses: Payment and subscription objects include custom_field_responses

Subscription Configuration

object

Additional configuration for checkout sessions containing subscription products.

Hiện Subscription data object properties

integer

Number of days for the trial period before the first charge. Must be between 0 and 10000 days.A paid trial amount cannot be set per session — configure trial_amount on the product’s recurring price instead. See Paid Trials.

object

On-demand subscription configuration for usage-based or metered billing.

Hiện On-demand object properties

boolean

bắt buộc

If set to true, does not perform any charge and only authorizes payment method details for future use.

integer

Product price for the initial charge to customer. If not specified, the stored price of the product will be used.Format: Represented in the lowest denomination of the currency (e.g., cents for USD). For example, to charge $1.00, pass 100.

string

Optional currency of the product price. If not specified, defaults to the currency of the product.

string

Optional product description override for billing and line items. If not specified, the stored description of the product will be used.

boolean

Whether adaptive currency fees should be included in the product price (true) or added on top (false). Ignored if adaptive pricing is not enabled.

Usage Examples

Here are 10 comprehensive examples showcasing different checkout session configurations for various business scenarios:

1. Simple Single Product Checkout

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

2. Multi-Product Cart

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

3. Subscription with Trial Period

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

4. Pre-confirmed Checkout

When confirm is set to true, the customer will be taken directly to the checkout page, bypassing any confirmation steps.

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

5. Checkout with Currency Override

The billing_currency override only takes effect when adaptive currency is enabled in your account settings. If adaptive currency is disabled, this parameter will have no effect.

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

6. Saved Payment Methods for Returning Customers

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

7. B2B Checkout with Tax ID Collection

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

8. Dark Theme Checkout with Stacked Discount Codes

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

9. Regional Payment Methods (UPI for India)

For detailed information about UPI configuration and testing, see the India Payment Methods page.

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

10. BNPL (Buy Now Pay Later) Checkout

For detailed information about BNPL configuration and testing, see the Buy Now Pay Later (BNPL) page.

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

11. Using Existing Payment Methods for Instant Checkout

Use a customer’s saved payment method to create a checkout session that processes immediately, skipping payment method collection:

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

When using payment_method_id, confirm must be set to true and an existing customer_id must be provided. The payment method will be validated for eligibility with the payment’s currency. Because the charge is processed immediately, checkout_url is returned as null — use the returned payment_id instead.

The payment method must belong to the customer and be compatible with the payment currency. This enables one-click purchases for returning customers.

12. Short Links for Cleaner Payment URLs

Generate shortened, shareable payment links with custom slugs:

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

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

Short links are perfect for SMS, email, or social media sharing. They’re easier to remember and build more customer trust than long URLs.

13. Skip Payment Success Page with Immediate Redirect

Redirect customers immediately after payment completion, bypassing the default success page:

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

Use redirect_immediately: true when you have a custom success page that provides better user experience than the default payment success page. This is especially useful for mobile apps and embedded checkout flows.

When redirect_immediately is enabled, customers are redirected to your return_url immediately after payment completion, skipping the default success page entirely.

14. Forcing a Language

Force the checkout to display in a specific language, overriding the customer’s browser language detection:

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

Use force_language when you know your customer’s preferred language (e.g., from their account settings) or when targeting specific regional markets.

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

15. Collecting Custom Fields

Collect additional information from customers during checkout using custom fields:

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

Custom field responses are automatically included in webhook payloads (payment.succeeded, subscription.active, etc.) and can be retrieved via the API. Use them to enrich your CRM, trigger onboarding flows, or customize the customer experience.

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

Previewing Checkout Sessions

Before creating a checkout session, you can preview the pricing breakdown including taxes, discounts, and totals. This is useful for displaying accurate pricing to customers before they proceed to checkout.

Giá trị current_breakup.subtotal trong bản xem trước đã phản ánh Purchasing Power Parity và Charm Pricing khi 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ý, phản hồi xem trước cũng trả về 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 đăng ký được tạo. Giá trị được tính tương đối với thời điểm hiện tại: now + trial period khi áp dụng thời gian dùng thử, nếu không thì là now + one payment frequency. Trường này bị bỏ qua đối với giỏ hàng chỉ chứa sản phẩm mua 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 thiết lập khi đăng ký đượ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ó tính phí) và trial_amount (phí dùng thử trên mỗi đơn vị sau khi giảm giá, tính theo đơn vị nhỏ nhất của loại tiền tệ dùng cho giá). trial_amount chỉ xuất hiện với paid trial và có giá trị null đối với thời gian dùng thử miễn phí hoặc không có thời gian dùng thử. Sử dụng current_breakup cho tổng tiền đã bao gồm thuế thực sự đến hạn thanh toán hôm nay.

Node.js SDK
Python SDK

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

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

// Present only when the cart contains a subscription product
console.log('Next billing date:', preview.next_billing_date);

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

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

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

Preview API Reference

Xem tài liệu đầy đủ về endpoint xem trước.

Chuyển từ Dynamic Links sang Checkout Sessions

Những khác biệt chính

Trước đây, khi tạo liên kết thanh toán bằng Dynamic Links, bạn bắt buộc phải cung cấp địa chỉ thanh toán đầy đủ của khách hàng. Với Checkout Sessions, điều này không còn cần thiết. Bạn chỉ cần truyền bất kỳ thông tin nào mình có, phần còn lại chúng tôi sẽ xử lý. 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 thông tin đó.
Luồng thanh toán sẽ tự động thu thập các thông tin còn thiếu trước khi chuyển khách hàng đến trang thanh toán.
Ngược lại, nếu bạn đã có tất cả thông tin bắt buộc và muốn chuyển thẳng đến trang thanh toán, bạn có thể truyền toàn bộ tập dữ liệu và thêm confirm=true vào request body.

Quy trình di chuyển

Việc chuyển từ Dynamic Links sang Checkout Sessions 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 thức API hoặc SDK mới.

Adjust request payload

Điều chỉnh payload của request theo định dạng Checkout Sessions.

That's it!

Có. Bạn không cần thực hiện thêm bất kỳ thao tác xử lý hoặc bước di chuyển đặc biệt nào.

Tài liệu tham khảo API liên quan

Create Checkout Session

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

Preview Checkout Session

Tài liệu tham khảo API để xem trước giá, thuế và tổng tiền trước khi tạo phiên

Integration Guides

Billing Deconstructions

Cookbooks

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

Optional Fields

Country Code Reference

Usage Examples

1. Simple Single Product Checkout

2. Multi-Product Cart

3. Subscription with Trial Period

4. Pre-confirmed Checkout

5. Checkout with Currency Override

6. Saved Payment Methods for Returning Customers

7. B2B Checkout with Tax ID Collection

8. Dark Theme Checkout with Stacked Discount Codes

9. Regional Payment Methods (UPI for India)

10. BNPL (Buy Now Pay Later) Checkout

11. Using Existing Payment Methods for Instant Checkout

12. Short Links for Cleaner Payment URLs

13. Skip Payment Success Page with Immediate Redirect

14. Forcing a Language

15. Collecting Custom Fields

Previewing Checkout Sessions

Preview API Reference

Chuyển từ Dynamic Links sang Checkout Sessions

Những khác biệt chính

Quy trình di chuyển

Tài liệu tham khảo API liên quan

Create Checkout Session

Preview Checkout Session

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

​Optional Fields

Country Code Reference

​Usage Examples

​1. Simple Single Product Checkout

​2. Multi-Product Cart

​3. Subscription with Trial Period

​4. Pre-confirmed Checkout

​5. Checkout with Currency Override

​6. Saved Payment Methods for Returning Customers

​7. B2B Checkout with Tax ID Collection

​8. Dark Theme Checkout with Stacked Discount Codes

​9. Regional Payment Methods (UPI for India)

​10. BNPL (Buy Now Pay Later) Checkout

​11. Using Existing Payment Methods for Instant Checkout

​12. Short Links for Cleaner Payment URLs

​13. Skip Payment Success Page with Immediate Redirect

​14. Forcing a Language

​15. Collecting Custom Fields

​Previewing Checkout Sessions

Preview API Reference

​Chuyển từ Dynamic Links sang Checkout Sessions

​Những khác biệt chính

​Quy trình di chuyển

​Tài liệu 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

Optional Fields

Usage Examples

1. Simple Single Product Checkout

2. Multi-Product Cart

3. Subscription with Trial Period

4. Pre-confirmed Checkout

5. Checkout with Currency Override

6. Saved Payment Methods for Returning Customers

7. B2B Checkout with Tax ID Collection

8. Dark Theme Checkout with Stacked Discount Codes

9. Regional Payment Methods (UPI for India)

10. BNPL (Buy Now Pay Later) Checkout

11. Using Existing Payment Methods for Instant Checkout

12. Short Links for Cleaner Payment URLs

13. Skip Payment Success Page with Immediate Redirect

14. Forcing a Language

15. Collecting Custom Fields

Previewing Checkout Sessions

Chuyển từ Dynamic Links sang Checkout Sessions

Những khác biệt chính

Quy trình di chuyển

Tài liệu tham khảo API liên quan