Quick Start
Create your first checkout session in under 5 minutes
API Reference
Full API documentation and interactive testing
Preview Endpoint
Calculate pricing and taxes before creating a session
Session Validity: Checkout sessions expire after 24 hours by default, or 15 minutes when
confirm: true.Prerequisites
You need:- An active Dodo Payments merchant account
- API credentials from Developer → API Keys in the dashboard
- At least one product created in Products
Creating Your First Checkout Session
- Node.js SDK
- Python SDK
- REST API
API Response
All methods return:session_id is guaranteed to be present. When payment_method_id is provided, the charge processes immediately and checkout_url is null. Use the returned payment_id instead.
When confirm: true, the payment is created at session-creation time, and the response also includes payment_id, client_secret, and publishable_key for use with the Dodo Payments checkout SDK.
Redirect Your Customer
1
Extract the checkout URL
Get
checkout_url from the API response.2
Redirect to checkout
Send your customer to the URL:Alternatively, open in a new window:
3
Handle the return
After payment, customers are redirected to your
return_url with query parameters:Example redirect:
세션 상태 확인
세션의 상태를 확인하려면 Checkout Session 가져오기 (GET /checkouts/{id})를 호출하세요. 응답에는 세션의 id, created_at, customer_email, customer_name와 payment_id 및 payment_status가 포함됩니다. 고객이 아직 세부 정보를 입력하는 동안에는 두 결제 필드 모두 null입니다. 고객이 결제를 제출하면 payment_status에 succeeded, failed 또는 processing와 같은 결제 상태가 저장됩니다. 이행 처리의 기준 데이터로 webhook을 사용하세요.
요청 본문
필수 필드
array
필수
Checkout Session에 포함할 제품 배열입니다. 각 제품에는 대시보드의 유효한
product_id가 있어야 합니다.동일한 세션에서 일회성 결제 제품과 구독 제품을 함께 사용할 수 있습니다.선택적 필드
Customer Information
Customer Information
Payment Configuration
Payment Configuration
array
결제 중 고객에게 제공할 결제 수단을 제어합니다. 특정 시장이나 비즈니스 요구 사항에 맞게 최적화할 수 있습니다.일반적인 옵션:
credit, debit, upi_collect, apple_pay, google_pay, amazon_pay, klarna, affirm, afterpay_clearpay, cashapp, ach, multibanco, bancontact_card, eps, ideal, blik, gcash, ali_pay_hk, fps, touch_n_go, paypal전체 목록은 Create Checkout Session API reference를 참조하세요.예시:string
기본 통화 선택을 고정된 청구 통화로 재정의합니다. ISO 4217 통화 코드를 사용합니다.지원 통화:
USD, EUR, GBP, CAD, AUD, INR 등예시: 미국 달러는 "USD", 유로는 "EUR"이 필드는 adaptive pricing이 활성화된 경우에만 적용됩니다. adaptive pricing이 비활성화되면 제품의 기본 통화가 사용됩니다.boolean
기본값:"false"
재방문 고객에게 저장된 결제 수단을 표시하여 결제 속도와 사용자 경험을 개선합니다.
Session Management
Session Management
string
결제가 완료된 후 고객을 리디렉션할 URL입니다. Dodo Payments는 리디렉션 시 URL에 query parameter를 추가합니다(위의 리디렉션 표 참조).예시 리디렉션 URL:
license_key 및 email query parameter를 사용하면 추가 API 호출 없이 return page에서 라이선스 키를 표시하거나 즉시 확인 메시지를 보낼 수 있습니다.string
고객이 뒤로 가기 버튼을 클릭하거나 Checkout Session을 취소했을 때 리디렉션할 URL입니다. 제공하지 않으면 뒤로 가기 버튼이 표시되지 않습니다.고객이 구매를 완료하지 않고도 사이트로 돌아갈 수 있도록 명확한 방법을 제공하려면
cancel_url를 설정하세요.boolean
기본값:"false"
true인 경우 모든 세션 세부 정보를 즉시 확정합니다. 필수 데이터가 누락되면 API에서 오류가 발생합니다.
confirm: true인 경우:- 모든 청구지 주소 필드가 필수가 됩니다
payment_method_id를 제공하여 즉시 청구를 처리할 수 있습니다- 세션 만료 시간이 24시간이 아닌 15분으로 설정됩니다
payment_method_id가 제공되면 기존customer_id가 필요합니다
array
하나 이상의 누적 할인 코드를 Checkout Session에 적용합니다. 코드는 배열 순서대로 적용됩니다(첫 번째 코드는 시작 가격을 낮추고, 두 번째 코드는 할인된 가격을 다시 낮추는 방식). 세션당 최대 20개까지 사용할 수 있습니다.Purchasing Power Parity가 활성화된 경우 시작 가격은 기본 가격이 아닌 PPP 조정 금액입니다.아래의 단일
discount_code 필드는 더 이상 사용되지 않지만 계속 완전히 지원됩니다. 동일한 요청에서 discount_codes와 함께 사용할 수 없습니다.string
지원 중단
Deprecated — 새 통합에는
discount_codes를 사용하세요. 이전 버전과의 호환성을 위해 계속 작동하지만 동일한 요청에서 discount_codes와 함께 사용할 수 없습니다.object
세션에 대한 추가 정보를 저장할 사용자 지정 key-value 쌍입니다.
boolean
이 세션에 대한 merchant 기본 3DS 동작을 재정의합니다.
boolean
기본값:"false"
최소 주소 수집 모드를 활성화합니다. 활성화하면 checkout에서 다음 정보만 수집합니다:
- Country: 세금 산정을 위해 항상 필요
- ZIP/Postal code: sales tax, VAT 또는 GST 계산에 필요한 지역에서만 수집
string
연결된 고객에게 속한 저장된 결제 수단입니다.
confirm: true 및 기존 customer.customer_id가 필요합니다. 결제 수단은 결제 통화에 대한 적합성 검증을 거칩니다. 설정하면 청구가 즉시 처리되고 checkout_url가 null로 반환됩니다. 대신 반환된 payment_id를 사용하세요.boolean
기본값:"false"
true인 경우 전체 세션 URL 대신 단축 checkout URL을 반환합니다.
string
collection 기반 checkout flow를 위한 제품 collection ID입니다. 설정할 때 빈
product_cart 배열을 전달하세요. 세션 생성 시 할인 코드를 미리 적용할 수 없습니다. Product Collections를 참조하세요.string
고객의 Tax ID(예: VAT 번호)입니다.
billing_address와 country가 필요합니다.string
Tax ID와 연결된 선택적 business 또는 법적 이름으로, 최대 250자입니다. 유효한
tax_id와 함께 제공하면 고객의 개인 이름 대신 청구서에 표시됩니다.integer
인도 카드의 INR e-mandate에 대해 merchant 수준 mandate floor(INR paise 단위)를 재정의합니다.processor로 전송되는 mandate 금액은
max(this_floor, actual_billing_amount)이므로 billing 금액이 더 낮을 때 고객에게 표시되는 authorization ceiling이 됩니다. 설정하지 않으면 merchant 설정이 적용되고, 이 설정도 없으면 시스템 기본값 ₹15,000이 적용됩니다.UI Customization
UI Customization
object
checkout interface의 모양과 동작을 사용자 지정합니다.
Feature Flags
Feature Flags
object
Checkout Session의 특정 기능과 동작을 구성합니다.
Custom Fields
Custom Fields
array
사용자 지정 form field를 사용해 checkout 중 고객으로부터 추가 정보를 수집합니다. Checkout Session당 최대 5개의 사용자 지정 필드를 정의할 수 있습니다. 고객 응답은 webhook payload에 포함되며 API를 통해 사용할 수 있습니다.
- Webhooks:
payment.succeeded,subscription.active및 기타 관련 event payload에custom_field_responses배열이 포함됩니다 - API 응답: Payment 및 subscription 객체에
custom_field_responses가 포함됩니다
Subscription Configuration
Subscription Configuration
object
구독 제품을 포함하는 Checkout Session의 추가 구성입니다.
사용 예시
단일 제품 간단 결제
여러 제품 장바구니
Trial 기간이 있는 구독
사전 확정된 결제
통화 재정의가 적용된 결제
재방문 고객을 위한 저장된 결제 수단
Tax ID 수집을 포함한 B2B 결제
누적 할인 코드가 적용된 다크 테마 결제
지역별 결제 수단(인도의 UPI)
UPI 구성 및 테스트에 대한 자세한 내용은 India Payment Methods 페이지를 참조하세요.BNPL(Buy Now Pay Later) 결제
BNPL 구성 및 테스트에 대한 자세한 내용은 Buy Now Pay Later (BNPL) 페이지를 참조하세요.기존 결제 수단을 사용한 즉시 결제
깔끔한 결제 URL을 위한 단축 링크
결제 성공 페이지를 건너뛰고 즉시 리디렉션
언어 지정
사용자 지정 필드 수집
Checkout Session 미리 보기
세션을 생성하기 전에 가격, 세금 및 합계를 계산하려면 Preview Checkout Session endpoint를 사용하세요. 사이트에 정확한 가격 정보를 표시할 때 유용합니다.미리 보기된
current_breakup.subtotal에는 제품에 적용되는 Purchasing Power Parity와 Charm Pricing이 이미 반영되어 있습니다.장바구니에 구독 제품이 포함되면 미리 보기 응답에
next_billing_date도 반환됩니다. 이는 구독 생성 전에 표시할 수 있는 다음 청구일 미리 보기입니다. 현재 시점을 기준으로 계산되며, trial이 적용되면 now + trial period, 그렇지 않으면 now + one payment frequency입니다. 일회성 제품만 포함된 장바구니에서는 이 필드가 생략됩니다. 이는 미리 보기 시점에 기준을 둔 추정값이며, 구독이 활성화될 때 권위 있는 next_billing_date가 설정됩니다.미리 보기에는
trial_period_days(유효 trial 기간, 무료 또는 유료)와 trial_amount(할인 후 가격 통화의 최소 단위로 표시된 단위당 trial 청구액)도 반환됩니다. trial_amount는 paid trial에만 존재하며 무료 trial 또는 trial 없음인 경우 null입니다. 오늘 실제로 납부해야 할 세금 포함 합계에는 current_breakup를 사용하세요.- Node.js SDK
- Python SDK
- REST API
Dynamic Links에서 마이그레이션
Dynamic Links를 사용 중이라면 Checkout Sessions가 더 많은 유연성을 제공합니다. Dynamic Links에서는 고객의 전체 청구지 주소를 제공해야 했습니다. Checkout Sessions에서는 보유한 정보만 전달하면 나머지는 checkout flow가 수집합니다. 예:- 고객의 청구 국가만 제공하면 checkout이 나머지 세부 정보를 수집합니다.
- 또는 모든 정보를 제공하고
confirm: true를 설정하여 결제 페이지로 바로 이동할 수 있습니다.
관련 리소스
Overlay Checkout
페이지에서 checkout을 modal overlay로 열기
Inline Checkout
페이지에 checkout 직접 삽입
Mobile Integration
native mobile app에 checkout 통합
Webhooks
결제 및 구독 event 수신
Payment Methods
지역별 지원 결제 수단
Subscriptions
recurring billing 및 구독 관리