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

session_id만 항상 포함됩니다. 두 가지 경우에는 추가 필드가 반환되거나 일부 필드가 반환되지 않습니다:

payment_method_id가 제공된 경우 — 결제가 즉시 처리되며 checkout_url는 null입니다. 대신 반환된 payment_id를 사용하세요.
confirm: true가 세션 생성 시점에 결제를 생성한 경우 — 응답에 Dodo Payments checkout SDK와 함께 사용할 payment_id, client_secret 및 publishable_key도 포함됩니다.

생성된 checkout_url는 일회성으로만 사용할 수 있으며 24시간 이내에 만료됩니다. 여러 고객 또는 결제 시도에 걸쳐 이를 캐시하거나 재사용하지 마세요. 새로운 링크가 필요할 때마다 새 checkout session을 생성하세요.

Get the checkout URL

API 응답에서 checkout_url를 추출합니다.

Redirect your customer

고객이 구매를 완료할 수 있도록 checkout URL로 안내하세요.

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

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

대체 통합 옵션: 리디렉션하는 대신 Overlay Checkout(모달 오버레이) 또는 Inline Checkout(완전 임베드)을 사용해 checkout을 페이지에 직접 삽입할 수 있습니다. 네이티브 모바일 앱에서는 동일한 URL을 Android, iOS, React Native 또는 Flutter용 Mobile Checkout SDKs에 전달하세요. 이 모든 방식은 동일한 checkout session URL을 사용합니다.

Handle the return

결제 후 고객은 결제/구독 ID, 상태, 고객 이메일 및 라이선스 키를 포함한 query parameters와 함께 return_url로 리디렉션됩니다. 전체 목록은 return_url parameter docs를 참조하세요.

Request Body

Required Fields

모든 checkout session에 필요한 필수 필드

Optional Fields

checkout 환경을 맞춤 설정하기 위한 추가 구성

Required Fields

array

필수

checkout session에 포함할 제품 배열입니다. 각 제품에는 Dodo Payments dashboard의 유효한 product_id가 있어야 합니다.

Mixed Checkout: 동일한 checkout session에서 일회성 결제 제품과 구독 제품을 함께 사용할 수 있습니다. 이를 통해 구독 설정 수수료, SaaS와 하드웨어 번들 등 강력한 사용 사례를 구현할 수 있습니다.

표시 Product Cart Item Properties

string

필수

Dodo Payments dashboard에 있는 제품의 고유 식별자입니다.Example: "prod_123abc456def"

integer

필수

제품 수량입니다.Example: 단일 항목은 1, 여러 수량은 3

array

제품에 연결할 addon 배열입니다. 제품이 구독인 경우에만 유효합니다.

표시 Addon item properties

string

필수

integer

필수

integer

pay_what_you_want가 활성화된 경우 고객이 결제하는 금액입니다. 비활성화된 경우 이 필드는 무시됩니다.Format: 통화의 최소 단위로 표시합니다(예: USD의 센트). 예를 들어 $1.00를 청구하려면 100를 전달합니다.

array

이 제품에 이미 연결된 credit entitlements에 대한 checkout session별 재정의입니다. 별도의 제품을 만들지 않고 이 단일 세션에 다른 크레딧 수를 부여할 때 사용하세요. 예를 들어 제품 기본값인 API 크레딧 500개 대신 프로모션 번들로 1,000개를 부여할 수 있습니다.

각 credit_entitlement_id는 제품에 이미 연결되어 있어야 합니다. 이 필드는 이 세션이 fulfill될 때 부여되는 credits_amount만 재정의하며, 제품 수준의 credit entitlement 설정(만료, rollover 등)은 계속 적용됩니다.

표시 Credit entitlement override properties

string

필수

재정의할 credit entitlement의 ID입니다. 제품에 이미 연결되어 있어야 합니다.

string

필수

이 checkout session에 부여할 크레딧 수이며 제품 수준의 credits_amount를 재정의합니다. 0보다 커야 합니다.

제품 ID 찾기: Dodo Payments dashboard의 Products → View Details에서 제품 ID를 확인하거나 List Products API를 사용하세요.

Optional Fields

checkout 환경을 맞춤 설정하고 결제 흐름에 비즈니스 로직을 추가하려면 이 필드를 구성하세요.

Customer Information

object

고객 정보입니다. ID를 사용해 기존 고객을 연결하거나 checkout 중에 새 customer record를 생성할 수 있습니다.

Attach Existing Customer
New Customer

ID를 사용해 기존 고객을 checkout session에 연결합니다.

표시 Existing Customer Properties

string

필수

기존 고객의 고유 식별자입니다. 새 고객을 생성하는 대신 checkout session을 기존 고객에게 연결할 때 사용합니다.

checkout 중에 새 customer record를 생성합니다.

표시 New Customer Properties

string

필수

고객의 이메일 주소입니다. 새 고객을 생성할 때 필요합니다.

string

영수증과 invoice에 표시할 고객의 전체 이름입니다.Example: "John Doe" 또는 "Jane Smith"

string

국제 형식의 고객 전화번호입니다. 일부 결제 수단 및 fraud prevention에 필요합니다.Format: 국가 코드를 포함하세요. 예: 미국 번호의 경우 "+1234567890"

object

정확한 세금 계산, fraud prevention 및 regulatory compliance를 위한 청구지 주소 정보입니다.

confirm가 true로 설정되면 성공적인 세션 생성을 위해 모든 청구지 주소 필드가 필수가 됩니다.

표시 Billing address object properties

string

번지, 도로명, 해당하는 경우 아파트/호수 번호를 포함한 전체 도로 주소입니다.Example: "123 Main St, Apt 4B" 또는 "456 Oak Avenue"

string

도시 또는 지방자치단체 이름입니다.Example: "San Francisco", "New York", "London"

string

주, 도, 또는 지역 이름입니다. 전체 이름이나 표준 약어를 사용하세요.Example: "California" 또는 "CA", "Ontario" 또는 "ON"

string

필수

두 자리 ISO 국가 코드(ISO 3166-1 alpha-2)입니다. billing_address가 제공되면 이 필드는 항상 필수입니다.Examples: "US"(미국), "CA"(캐나다), "GB"(영국), "DE"(독일)

Country Code Reference

지원되는 국가와 ISO 코드의 전체 목록 보기

string

국가별 요구사항에 따른 우편번호, ZIP code 또는 이에 상응하는 값입니다.Examples: "94102"(미국), "M5V 3A8"(캐나다), "SW1A 1AA"(영국)

Payment Configuration

array

checkout 중 고객에게 제공할 결제 수단을 제어합니다. 특정 시장 또는 비즈니스 요구사항에 맞게 최적화하는 데 도움이 됩니다.Common options: credit, debit, upi_collect, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, cashapp, multibanco, bancontact_card, eps, ideal, przelewy24, paypal. 전체 목록은 아니므로 모든 허용 값을 확인하려면 Create Checkout Session API reference를 참조하세요.

중요: 선호하는 결제 수단을 사용할 수 없을 때 checkout 실패를 방지하려면 항상 credit 및 debit를 fallback 옵션으로 포함하세요.

Example:

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

string

기본 통화 선택을 고정된 청구 통화로 재정의합니다. ISO 4217 currency codes를 사용합니다.Supported Currencies: USD, EUR, GBP, CAD, AUD, INR 등Example: 미국 달러는 "USD", 유로는 "EUR"

이 필드는 adaptive pricing이 활성화된 경우에만 적용됩니다. adaptive pricing이 비활성화되면 제품의 기본 통화가 사용됩니다.

boolean

기본값:"false"

재방문 고객에게 이전에 저장한 결제 수단을 표시하여 checkout 속도와 사용자 경험을 개선합니다.

Session Management

string

결제 완료 후 고객을 리디렉션할 URL입니다. 리디렉션 시 Dodo Payments는 다음 query parameters를 URL에 추가합니다:

Parameter	Type	Condition
`payment_id`	`string`	일회성 결제에 항상 포함
`subscription_id`	`string`	구독 결제에 항상 포함
`status`	`string`	항상 포함
`license_key`	`string`	제품에서 license keys가 활성화된 경우 포함. 여러 키가 있으면 쉼표로 구분
`email`	`string`	고객의 이메일이 등록되어 있는 경우 포함

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

license_key 및 email query parameters를 사용하면 추가 API 호출 없이 return page에서 license keys를 표시하거나 즉시 확인 메시지를 보낼 수 있습니다.

string

고객이 뒤로 가기 버튼을 클릭하거나 checkout session을 취소했을 때 리디렉션할 URL입니다. 제공하지 않으면 뒤로 가기 버튼이 표시되지 않습니다.

고객이 구매를 완료하지 않고 사이트로 돌아갈 수 있는 명확한 방법을 제공하려면 cancel_url를 설정하세요. checkout 경험이 개선되고 마찰이 줄어듭니다.

boolean

기본값:"false"

true인 경우 모든 세션 세부정보를 즉시 확정합니다. 필수 데이터가 누락되면 API가 오류를 발생시킵니다.

array

checkout session에 하나 이상의 누적 discount codes를 적용합니다. 코드는 배열 순서대로 적용되며(첫 번째 코드는 기본 가격을 낮추고, 두 번째 코드는 이미 할인된 가격을 낮추는 방식), 세션당 최대 20개까지 사용할 수 있습니다.

discount_codes: ['WELCOME10', 'BLACKFRIDAY20']

아래의 단일 discount_code 필드는 deprecated 상태이지만 여전히 완전히 지원됩니다. 기존 통합은 변경 없이 계속 작동합니다. 동일한 요청에서 discount_codes와 함께 사용할 수 없습니다. 누적 할인 기능을 활용하려면 편리한 시점에 discount_codes로 마이그레이션하세요.

string

지원 중단

Deprecated — 새로운 통합에서는 discount_codes를 사용하세요. 이 필드는 backward compatibility를 위해 계속 작동하지만 동일한 요청에서 discount_codes와 함께 사용할 수 없습니다.

object

세션에 대한 추가 정보를 저장할 사용자 지정 key-value 쌍입니다.

boolean

이 세션에 대한 merchant 기본 3DS 동작을 재정의합니다.

boolean

기본값:"false"

최소 주소 수집 모드를 활성화합니다. 활성화하면 checkout에서는 다음 항목만 수집합니다:

Country: 세금 산정을 위해 항상 필수
ZIP/Postal code: sales tax, VAT 또는 GST 계산에 필요한 지역에서만 수집

불필요한 양식 필드를 제거하여 checkout 마찰을 크게 줄입니다.

더 빠른 checkout 완료를 위해 최소 주소를 활성화합니다. 전체 청구 세부정보가 필요한 비즈니스에서는 전체 주소 수집을 계속 사용할 수 있습니다.

string

연결된 고객에게 속한 저장된 결제 수단입니다. confirm: true 및 기존 customer.customer_id가 필요합니다. 설정하면 결제가 즉시 처리되고 checkout_url가 null로 반환됩니다. 대신 반환된 payment_id를 사용하세요.

boolean

기본값:"false"

true인 경우 전체 session URL 대신 단축 checkout URL을 반환합니다.

string

collection 기반 checkout flow를 위한 제품 collection ID입니다.

string

고객의 Tax ID입니다(예: VAT 번호). billing_address와 country가 필요합니다.

string

Tax ID와 연결된 선택적 business 또는 legal name입니다. 유효한 tax_id와 함께 제공하면 invoice에 고객의 개인 이름 대신 표시됩니다.

integer

인도 카드의 INR e-mandate에 대해 merchant 수준의 mandate floor(INR paise 단위)를 재정의합니다.

UI Customization & Features

object

checkout interface의 모양과 동작을 맞춤 설정합니다.

표시 Customization object properties

string

기본값:"system"

checkout interface의 테마입니다. 옵션: light, dark 또는 system.

boolean

기본값:"true"

checkout interface에 주문 세부정보 섹션을 표시합니다.

boolean

기본값:"true"

해당 제품에 “on-demand” 태그를 표시합니다.

string

checkout interface를 특정 언어로 렌더링합니다. 기본적으로 checkout은 고객 브라우저의 언어를 자동 감지합니다.지원되는 언어 코드: ar(아랍어), ca(카탈루냐어), de(독일어), en(영어), es(스페인어), fr(프랑스어), he(히브리어), id(인도네시아어), it(이탈리아어), ja(일본어), ko(한국어), ms(말레이어), nl(네덜란드어), pl(폴란드어), pt(포르투갈어), ro(루마니아어), ru(러시아어), sv(스웨덴어), th(태국어), tr(터키어), zh(중국어)Example: 스페인어는 "es", 일본어는 "ja"

object

light 및 dark mode의 색상, fonts 및 button styling을 포함한 사용자 지정 theme 구성입니다. deprecated된 client-side themeConfig 옵션을 server-side에서 대체합니다.

표시 Theme config properties

object

Light mode 색상 구성입니다.

object

Dark mode 색상 구성입니다.

string

기본 font의 URL입니다. 유효한 https:// URL이어야 합니다.

string

보조 font의 URL입니다. 유효한 https:// URL이어야 합니다.

string

checkout UI의 font size입니다. 옵션: xs, sm, md, lg, xl, 2xl.

string

checkout UI의 font weight입니다. 옵션: normal, medium, bold, extraBold.

string

pay button에 표시할 사용자 지정 텍스트입니다(예: "Complete Purchase" 또는 "Subscribe Now"). 최대 100자입니다.

string

UI 요소의 border radius입니다. px, rem 또는 em가 뒤따르는 숫자입니다(예: "4px", "0.5rem", "1em").

object

checkout session의 특정 기능과 동작을 구성합니다.

표시 Feature flags object properties

boolean

기본값:"true"

checkout 중 고객이 선호하는 통화를 선택할 수 있도록 합니다.

boolean

기본값:"true"

checkout interface에 discount code 입력 필드를 표시합니다.

boolean

기본값:"false"

checkout 중 고객이 구독 제품의 addon을 추가하거나 제거할 수 있도록 합니다. 구독 제품에만 적용됩니다.

boolean

기본값:"true"

checkout 중 고객의 전화번호를 수집합니다.

boolean

기본값:"false"

checkout을 완료하려면 고객이 전화번호를 제공하도록 요구합니다. allow_phone_number_collection도 true여야 합니다.

boolean

기본값:"true"

고객이 tax identification numbers를 입력할 수 있도록 합니다.

boolean

기본값:"false"

기존 customer record를 업데이트하는 대신 새 customer record를 생성하도록 합니다.

boolean

checkout 중 고객이 이메일 주소를 수정할 수 있도록 합니다.

boolean

checkout 중 고객이 이름을 수정할 수 있도록 합니다.

boolean

checkout 중 고객이 도로 주소를 수정할 수 있도록 합니다.

boolean

checkout 중 고객이 도시를 수정할 수 있도록 합니다.

boolean

checkout 중 고객이 주/도를 수정할 수 있도록 합니다.

boolean

checkout 중 고객이 국가를 수정할 수 있도록 합니다.

boolean

checkout 중 고객이 zipcode를 수정할 수 있도록 합니다.

boolean

checkout 중 고객이 Tax ID를 입력하거나 수정할 수 있도록 합니다.

boolean

기본값:"false"

고객이 Tax ID와 연결된 business name을 입력하거나 수정할 수 있도록 합니다. allow_customer_editing_tax_id와 독립적으로 작동하며, 두 플래그 중 하나(또는 allow_tax_id)만 설정해도 충분합니다. 일반적으로 allow_customer_editing_tax_id와 함께 설정합니다.

boolean

기본값:"false"

기본 결제 성공 페이지를 건너뛰고 결제 완료 후 고객을 즉시 return_url로 리디렉션합니다.

더 나은 사용자 경험을 제공하는 사용자 지정 성공 페이지가 있거나 mobile apps 및 embedded checkout flow를 사용하는 경우 활용하세요.

Custom Fields

array

사용자 지정 form fields를 사용해 checkout 중 고객으로부터 추가 정보를 수집합니다. checkout session당 최대 5개의 사용자 지정 필드를 정의할 수 있습니다. 고객 응답은 webhook payload에 포함되며 API를 통해 사용할 수 있습니다.

표시 Custom field object properties

string

필수

이 필드의 고유 식별자입니다. webhook payload와 API response에서 key로 사용됩니다.Example: "company_name", "referral_source", "team_size"

string

필수

checkout form에서 고객에게 표시되는 label입니다.Example: "Company Name", "How did you hear about us?", "Team Size"

string

필수

입력 validation rules를 결정하는 필드 유형입니다.Available types:

text - 한 줄 텍스트 입력
number - 숫자 입력
email - validation이 적용된 이메일 주소
url - validation이 적용된 URL
date - 날짜 선택기
dropdown - 사전 정의된 옵션에서 선택
boolean - Yes/No 토글

boolean

기본값:"false"

checkout을 완료하기 전에 이 필드를 입력해야 하는지 여부입니다.

string

입력 필드에 표시되는 placeholder text입니다.

array

dropdown 필드 유형을 위한 옵션 목록입니다. field_type가 dropdown인 경우 필수이며 다른 유형에서는 무시됩니다.Example: ["Google", "Twitter", "Friend referral", "Other"]

사용자 지정 필드에 대한 고객 응답은 다음에 포함됩니다:

Webhooks: payment.succeeded, subscription.active 및 기타 관련 event payload에 custom_field_responses 배열이 포함됩니다.
API responses: Payment 및 subscription object에 custom_field_responses가 포함됩니다.

Subscription Configuration

object

구독 제품이 포함된 checkout session을 위한 추가 구성입니다.

표시 Subscription data object properties

integer

첫 번째 charge 전 trial period의 일수입니다. 0일에서 10000일 사이여야 합니다.세션별로 paid trial amount를 설정할 수 없습니다. 대신 제품의 recurring price에서 trial_amount를 구성하세요. Paid Trials를 참조하세요.

object

usage-based 또는 metered billing을 위한 on-demand subscription 구성입니다.

표시 On-demand object properties

boolean

필수

true로 설정하면 charge를 수행하지 않고 향후 사용을 위해 payment method 세부정보만 authorize합니다.

integer

고객에게 부과할 initial charge의 제품 가격입니다. 지정하지 않으면 제품의 저장된 가격이 사용됩니다.Format: 통화의 최소 단위로 표시합니다(예: USD의 센트). 예를 들어 $1.00를 청구하려면 100를 전달합니다.

string

제품 가격의 선택적 통화입니다. 지정하지 않으면 제품의 통화가 기본값으로 사용됩니다.

string

billing 및 line items에 사용할 선택적 제품 설명 재정의입니다. 지정하지 않으면 제품에 저장된 설명이 사용됩니다.

boolean

adaptive currency fees를 제품 가격에 포함할지(true) 또는 추가할지(false) 여부입니다. adaptive pricing이 활성화되지 않은 경우 무시됩니다.

Usage Examples

다음은 다양한 비즈니스 시나리오에 맞는 checkout session 구성을 보여주는 10가지 종합 예시입니다:

1. 단일 제품의 간단한 Checkout

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. 여러 제품 장바구니

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. Trial Period가 포함된 구독

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. 사전 확정된 Checkout

confirm가 true로 설정되면 고객은 모든 확인 단계를 건너뛰고 checkout page로 바로 이동합니다.

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. 통화 재정의가 적용된 Checkout

billing_currency 재정의는 account settings에서 adaptive currency가 활성화된 경우에만 적용됩니다. adaptive currency가 비활성화되면 이 parameter는 적용되지 않습니다.

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. 재방문 고객을 위한 저장된 결제 수단

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. Tax ID 수집을 포함한 B2B Checkout

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. 누적 Discount Codes가 적용된 Dark Theme Checkout

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. 지역별 결제 수단(인도의 UPI)

UPI 구성 및 테스트에 대한 자세한 내용은 India Payment Methods 페이지를 참조하세요.

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. BNPL(Buy Now Pay Later) Checkout

BNPL 구성 및 테스트에 대한 자세한 내용은 Buy Now Pay Later (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. 즉시 Checkout을 위한 기존 결제 수단 사용

고객의 저장된 결제 수단을 사용해 즉시 처리되는 checkout session을 생성하고 결제 수단 수집을 건너뜁니다:

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

payment_method_id를 사용할 때는 confirm를 true로 설정하고 기존 customer_id를 제공해야 합니다. payment method는 결제 통화에 대한 사용 가능 여부가 검증됩니다. charge가 즉시 처리되므로 checkout_url가 null로 반환됩니다. 대신 반환된 payment_id를 사용하세요.

payment method는 고객에게 속해야 하며 결제 통화와 호환되어야 합니다. 이를 통해 재방문 고객에게 one-click purchase를 제공할 수 있습니다.

12. 더 깔끔한 결제 URL을 위한 Short Links

사용자 지정 slug를 사용해 공유 가능한 단축 결제 링크를 생성합니다:

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

Short links는 SMS, 이메일 또는 소셜 미디어 공유에 적합합니다. 긴 URL보다 기억하기 쉽고 고객 신뢰를 높일 수 있습니다.

13. 결제 성공 페이지를 건너뛰고 즉시 리디렉션

기본 성공 페이지를 거치지 않고 결제 완료 후 고객을 즉시 리디렉션합니다:

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

기본 결제 성공 페이지보다 더 나은 사용자 경험을 제공하는 사용자 지정 성공 페이지가 있는 경우 redirect_immediately: true를 사용하세요. mobile apps 및 embedded checkout flow에 특히 유용합니다.

redirect_immediately가 활성화되면 고객은 결제 완료 직후 기본 성공 페이지를 완전히 건너뛰고 return_url로 리디렉션됩니다.

14. 언어 강제 지정

고객 브라우저의 언어 감지를 재정의하여 checkout을 특정 언어로 표시합니다:

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

고객의 선호 언어를 알고 있는 경우(예: account settings에서 확인) 또는 특정 지역 시장을 대상으로 하는 경우 force_language를 사용하세요.

지원되는 언어: 아랍어(ar), 카탈루냐어(ca), 중국어(zh), 네덜란드어(nl), 영어(en), 프랑스어(fr), 독일어(de), 히브리어(he), 인도네시아어(id), 이탈리아어(it), 일본어(ja), 한국어(ko), 말레이어(ms), 폴란드어(pl), 포르투갈어(pt), 루마니아어(ro), 러시아어(ru), 스페인어(es), 스웨덴어(sv), 태국어(th), 터키어(tr)

15. 사용자 지정 필드 수집

사용자 지정 필드를 사용해 checkout 중 고객으로부터 추가 정보를 수집합니다:

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

사용자 지정 필드 응답은 webhook payload(payment.succeeded, subscription.active 등)에 자동으로 포함되며 API를 통해 가져올 수 있습니다. 이를 활용해 CRM을 보강하거나 onboarding flow를 트리거하고 고객 경험을 맞춤 설정하세요.

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

Checkout Sessions 미리 보기

checkout session을 생성하기 전에 세금, 할인 및 합계를 포함한 가격 내역을 미리 볼 수 있습니다. 고객이 checkout을 진행하기 전에 정확한 가격을 표시할 때 유용합니다.

장바구니에 구독 제품이 포함되면 preview response에 next_billing_date도 반환됩니다. 이는 예정된 청구일의 미리 보기이므로 구독이 생성되기 전에 표시할 수 있습니다. 현재 시점을 기준으로 계산되며, trial이 적용되면 now + trial period, 그렇지 않으면 now + one payment frequency입니다. 일회성 제품만 포함된 장바구니에서는 필드가 생략됩니다. 이는 preview 시점에 기준을 둔 추정치이며, 실제 next_billing_date는 구독이 활성화될 때 설정됩니다.

preview는 trial_period_days(유효 trial 기간, 무료 또는 유료) 및 trial_amount(할인 후 trial의 단위당 charge, 가격 통화의 최소 단위)도 반환합니다. trial_amount는 paid trial에만 포함되며 무료 trial 또는 trial이 없으면 null입니다. 오늘 실제로 납부해야 하는 세금 포함 합계에는 current_breakup를 사용하세요.

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.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": "prod_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

전체 preview endpoint 문서 보기

Dynamic Links에서 Checkout Sessions로 이전

주요 차이점

이전에는 Dynamic Links로 payment link를 생성할 때 고객의 전체 청구지 주소를 제공해야 했습니다. Checkout Sessions에서는 더 이상 필요하지 않습니다. 보유한 정보만 전달하면 나머지는 자동으로 처리됩니다. 예를 들어:

고객의 청구 국가만 알고 있다면 해당 정보만 제공하세요.
checkout flow가 결제 페이지로 이동하기 전에 누락된 세부정보를 자동으로 수집합니다.
반대로 필요한 정보를 이미 모두 보유하고 결제 페이지로 바로 이동하려면 전체 데이터 세트를 전달하고 request body에 confirm=true를 포함하세요.

Migration Process

Dynamic Links에서 Checkout Sessions로의 마이그레이션은 간단합니다:

Update your integration

새 API 또는 SDK method를 사용하도록 통합을 업데이트합니다.

Adjust request payload

Checkout Sessions format에 맞게 request payload를 조정합니다.

That's it!

예. 측에서 추가로 처리하거나 특별한 마이그레이션 단계를 수행할 필요는 없습니다.

Create Checkout Session

사용 가능한 모든 parameters와 options를 포함한 checkout session 생성 API reference

Preview Checkout Session

session 생성 전 가격, 세금 및 합계를 미리 보기 위한 API reference

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. 단일 제품의 간단한 Checkout

2. 여러 제품 장바구니

3. Trial Period가 포함된 구독

4. 사전 확정된 Checkout

5. 통화 재정의가 적용된 Checkout

6. 재방문 고객을 위한 저장된 결제 수단

7. Tax ID 수집을 포함한 B2B Checkout

8. 누적 Discount Codes가 적용된 Dark Theme Checkout

9. 지역별 결제 수단(인도의 UPI)

10. BNPL(Buy Now Pay Later) Checkout

11. 즉시 Checkout을 위한 기존 결제 수단 사용

12. 더 깔끔한 결제 URL을 위한 Short Links

13. 결제 성공 페이지를 건너뛰고 즉시 리디렉션

14. 언어 강제 지정

15. 사용자 지정 필드 수집

Checkout Sessions 미리 보기

Preview API Reference

Dynamic Links에서 Checkout Sessions로 이전

주요 차이점

Migration Process

관련 API Reference

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. 단일 제품의 간단한 Checkout

​2. 여러 제품 장바구니

​3. Trial Period가 포함된 구독

​4. 사전 확정된 Checkout

​5. 통화 재정의가 적용된 Checkout

​6. 재방문 고객을 위한 저장된 결제 수단

​7. Tax ID 수집을 포함한 B2B Checkout

​8. 누적 Discount Codes가 적용된 Dark Theme Checkout

​9. 지역별 결제 수단(인도의 UPI)

​10. BNPL(Buy Now Pay Later) Checkout

​11. 즉시 Checkout을 위한 기존 결제 수단 사용

​12. 더 깔끔한 결제 URL을 위한 Short Links

​13. 결제 성공 페이지를 건너뛰고 즉시 리디렉션

​14. 언어 강제 지정

​15. 사용자 지정 필드 수집

​Checkout Sessions 미리 보기

Preview API Reference

​Dynamic Links에서 Checkout Sessions로 이전

​주요 차이점

​Migration Process

​관련 API Reference

Create Checkout Session

Preview Checkout Session

Prerequisites

Creating Your First Checkout Session

API Response

Request Body

Required Fields

Optional Fields

Usage Examples

1. 단일 제품의 간단한 Checkout

2. 여러 제품 장바구니

3. Trial Period가 포함된 구독

4. 사전 확정된 Checkout

5. 통화 재정의가 적용된 Checkout

6. 재방문 고객을 위한 저장된 결제 수단

7. Tax ID 수집을 포함한 B2B Checkout

8. 누적 Discount Codes가 적용된 Dark Theme Checkout

9. 지역별 결제 수단(인도의 UPI)

10. BNPL(Buy Now Pay Later) Checkout

11. 즉시 Checkout을 위한 기존 결제 수단 사용

12. 더 깔끔한 결제 URL을 위한 Short Links

13. 결제 성공 페이지를 건너뛰고 즉시 리디렉션

14. 언어 강제 지정

15. 사용자 지정 필드 수집

Checkout Sessions 미리 보기

Dynamic Links에서 Checkout Sessions로 이전

주요 차이점

Migration Process

관련 API Reference