Skip to main content

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.
Single-Use Links: The checkout_url is not reusable. Generate a fresh session for each customer and payment attempt rather than sharing or reusing a link.

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

API Response

All methods return:
Only 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:
Instead of redirecting, you can embed checkout directly in your page using Overlay Checkout (modal), Inline Checkout (embedded), or Mobile SDKs (native apps). All consume the same session URL.

세션 상태 확인

세션의 상태를 확인하려면 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가 있어야 합니다.동일한 세션에서 일회성 결제 product와 subscription product 하나를 결합할 수 있습니다. 장바구니에는 subscription product를 두 개 이상 담을 수도 있지만, 이 경우 일회성 product는 담을 수 없습니다. Multi-Subscription Cart를 참조하세요. 장바구니에는 최대 20개의 product를 담을 수 있습니다.
제품 ID 찾기: Dodo Payments 대시보드의 Products → View Details에서 제품 ID를 확인하거나 List Products API를 사용할 수 있습니다.

선택적 필드

object
고객 정보입니다. 고객 ID를 사용해 기존 고객을 연결하거나 결제 중 새 고객 레코드를 만들 수 있습니다.
object
정확한 세금 계산, 사기 방지 및 규정 준수를 위한 청구지 주소 정보입니다.confirm: true인 경우, minimal_address가 true인 경우를 제외하고 모든 청구지 주소 필드가 필수가 됩니다.
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를 참조하세요.
선호하는 결제 수단을 사용할 수 없을 때 결제가 실패하지 않도록 credit와 debit를 대체 옵션으로 항상 포함하세요.
예시:
string
기본 통화 선택을 고정된 청구 통화로 재정의합니다. ISO 4217 통화 코드를 사용합니다.지원 통화: USD, EUR, GBP, CAD, AUD, INR 등예시: 미국 달러는 "USD", 유로는 "EUR"이 필드는 adaptive pricing이 활성화된 경우에만 적용됩니다. adaptive pricing이 비활성화되어 있으면 API가 이 필드를 삭제하고, 통화는 product 가격 또는 청구 국가에서 가져옵니다.
boolean
기본값:"false"
재방문 고객에게 저장된 결제 수단을 표시하여 결제 속도와 사용자 경험을 개선합니다.
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인 경우:
  • 모든 청구지 주소 필드가 필수가 됩니다(minimal_address가 true인 경우에는 country 및 zipcode만 해당)
  • 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 계산에 필요한 지역에서만 수집
불필요한 양식 필드를 제거하여 checkout 과정의 마찰을 크게 줄입니다.confirm: true를 사용하면 zipcode(country 포함)만 필수이며, 다른 청구지 주소 필드는 선택 사항으로 유지됩니다.
string
연결된 customer에 속한 저장된 payment method입니다. confirm: true 및 기존 customer.customer_id가 필요합니다. 결제 통화에 대한 사용 가능 여부를 확인합니다. 설정하면 요금이 즉시 처리되고 checkout_url가 null로 반환됩니다. 대신 반환된 payment_id를 사용하세요.
전체 세션 URL 대신 단축된 checkout URL을 반환합니다.
string
collection 기반 checkout flow를 위한 Product collection ID입니다. 설정할 때는 빈 product_cart 배열을 전달하세요. 세션 생성 시 discount code를 미리 적용할 수 없습니다. Product Collections을 참조하세요.
string
customer의 Tax ID(예: VAT 번호)입니다. billing_address와 country가 필요합니다.
string
Tax ID와 연결된 선택적 business 또는 법적 이름으로, 최대 250자입니다. 유효한 tax_id와 함께 제공하면 invoice에 customer의 개인 이름 대신 표시됩니다.
integer
인도 card의 INR e-mandate에 대해 merchant 수준의 mandate floor(INR paise 단위)를 재정의합니다.processor로 전송되는 mandate 금액은 max(this_floor, actual_billing_amount)이므로, billing 금액이 더 낮을 때 이는 사실상 customer에게 표시되는 authorization 한도입니다. 설정하지 않으면 merchant 설정이 적용되고, merchant 설정도 없으면 시스템 기본값인 ₹15,000이 적용됩니다.
object
checkout interface의 모양과 동작을 사용자 지정합니다.
object
checkout session의 특정 기능과 동작을 구성합니다.
array
custom form field를 사용하여 checkout 중 customer로부터 추가 정보를 수집합니다. checkout session마다 최대 5개의 custom field를 정의할 수 있습니다. customer 응답은 webhook payload에 포함되며 API를 통해 사용할 수 있습니다.
custom field에 대한 customer 응답은 다음에 포함됩니다.
  • Webhooks: payment.succeeded, subscription.active 및 기타 관련 event payload에 custom_field_responses 배열이 포함됩니다
  • API responses: Payment 및 subscription object에 custom_field_responses가 포함됩니다
object
subscription product가 포함된 checkout session의 추가 구성입니다.

사용 예시

단일 Product 간편 Checkout

Multi-Product Cart

Multi-Subscription Cart

하나의 checkout에서 여러 subscription product를 판매하려면 product_cart에 subscription product를 두 개 이상 추가하세요. customer는 한 번 결제하고, Dodo Payments는 각 product에 대해 하나의 payment, 하나의 invoice, 하나의 subscription을 생성합니다. 각 subscription은 고유한 billing cycle을 가지고 독립적으로 갱신되므로 monthly product와 annual product를 하나의 장바구니에서 함께 사용할 수 있습니다.
multi-subscription cart에는 다음과 같은 제한이 있습니다.
  • 일회성 product를 담을 수 없습니다. API는 422로 요청을 거부합니다.
  • 최대 20개의 subscription product를 담을 수 있습니다.
  • 동일한 product를 두 번 나열할 수 없습니다. product를 두 개 이상 판매하려면 대신 quantity를 설정하세요.
  • on-demand billing(subscription_data.on_demand)을 사용할 수 없습니다.
  • 장바구니에 적용된 discount code는 하나의 redemption으로 계산됩니다.
subscription_data.trial_period_days는 장바구니의 모든 subscription에 적용됩니다. 설정하지 않으면 각 subscription은 자체 product에 설정된 trial을 사용합니다. 설정하지 않은 상태에서 Prevent Trial Misuse가 켜져 있으면 customer가 이미 trial을 사용한 product는 trial 없이 시작됩니다. 결과 payment에는 is_multi_subscription: true가 있으며 subscription_ids에 시작되는 모든 subscription이 나열됩니다. 단일 subscription이 payment를 소유하지 않으므로 해당 subscription_id는 null입니다. payment.succeeded webhook에도 동일한 field가 포함됩니다. payment 유형을 확인하려면 is_multi_subscription를 읽고, subscription_ids의 길이로 판단하지 마세요. payment가 성공하면 장바구니에 대해 하나의 payment.succeeded event가, 각 subscription에 대해 하나의 subscription.active event가 수신됩니다. 그 후 각 subscription은 독립적으로 갱신, plan 변경 및 취소되며, 갱신마다 자체 invoice가 생성됩니다. 하나의 장바구니에서 생성된 모든 subscription은 customer가 checkout에서 사용한 payment method를 공유합니다. 그중 하나의 payment method를 update하면 Dodo Payments는 동일한 settlement currency와 billing currency를 사용하고 active, on_hold, past_due 또는 paused인 동일 장바구니의 모든 subscription으로 새 payment method를 이동합니다. product의 price currency가 서로 달라도 하나의 장바구니에서 생성된 모든 subscription은 동일한 settlement currency와 billing currency로 시작합니다. 이후 plan 변경과 같은 변경으로 subscription이 다른 settlement currency 또는 billing currency로 이동할 수 있습니다. 이 subscription은 기존 payment method를 유지하므로 별도로 update해야 합니다. on_hold subscription의 경우 update는 해당 subscription의 미납 invoice만 재시도합니다.

Trial Period가 있는 Subscription

사전 확인된 Checkout

Currency Override를 사용한 Checkout

Returning Customer를 위한 저장된 Payment Method

Tax ID 수집을 포함한 B2B Checkout

Stacked Discount Code를 사용한 Dark Theme Checkout

Regional Payment Method(인도의 UPI)

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

BNPL(Buy Now Pay Later) Checkout

BNPL 구성 및 테스트에 대한 자세한 내용은 Buy Now Pay Later (BNPL) page를 참조하세요.

기존 Payment Method를 사용한 Instant Checkout

Payment Success Page를 건너뛰고 즉시 Redirect

언어 강제 지정

Custom Field 수집

Checkout Session 미리 보기

session을 생성하기 전에 Preview Checkout Session endpoint를 사용하여 pricing, taxes 및 totals를 계산하세요. site에 정확한 pricing 정보를 표시할 때 유용합니다.
미리 본 current_breakup.subtotal에는 product에 적용되는 Purchasing Power Parity 및 Charm Pricing이 이미 반영되어 있습니다.
장바구니에 subscription product가 포함되면 preview response는 next_billing_date도 반환합니다. 이는 subscription이 생성되기 전에 표시할 수 있는 다음 billing date의 preview입니다. 현재 시점을 기준으로 계산되며, trial이 적용되면 now + trial period, 그렇지 않으면 now + one payment frequency입니다. 일회성 product만 포함된 장바구니에는 이 field가 생략됩니다. 이는 preview 시점에 기준을 둔 추정치이며, authoritative next_billing_date는 subscription이 활성화될 때 설정됩니다.
preview는 trial_period_days(유료 또는 무료인 실제 trial 기간) 및 trial_amount(discount 후 가격 currency의 최소 단위로 표시한 단위당 trial charge)도 반환합니다. trial_amount는 paid trial에만 존재하며 free trial 또는 trial이 없을 때는 null입니다. 오늘 실제로 납부해야 하는 세금 포함 total에는 current_breakup를 사용하세요.
multi-subscription cart의 경우 response는 subscription마다 하나의 항목이 있는 subscriptions 배열도 반환합니다. 항목에는 product_id, amount_due_now, tax_due_now, recurring_amount, recurring_tax, trial_period_days 및 next_billing_date가 포함됩니다. 최상위 next_billing_date는 장바구니에서 가장 이른 날짜이며, 최상위 trial_period_days와 trial_amount는 null입니다. 금액은 subscriptions 및 current_breakup에서 확인하세요. recurring_breakup는 갱신일이 서로 다르더라도 모든 subscription의 갱신 금액을 합산하므로 각 갱신 금액은 subscriptions에서 확인하세요.

Dynamic Links에서 마이그레이션

Dynamic Links를 사용 중이라면 Checkout Sessions가 더 많은 유연성을 제공합니다. Dynamic Links에서는 customer의 전체 billing address를 제공해야 했습니다. Checkout Sessions에서는 보유한 정보만 전달하면 checkout flow가 나머지 정보를 수집합니다. 예를 들면 다음과 같습니다.
  • customer의 billing country만 제공하면 checkout이 나머지 세부 정보를 수집합니다.
  • 또는 모든 정보를 제공하고 confirm: true를 설정하여 payment page로 바로 이동합니다.
마이그레이션은 간단합니다. integration을 업데이트하여 Checkout Sessions API 또는 SDK method를 사용하고, request payload를 Checkout Sessions 형식에 맞게 조정하면 완료됩니다. 추가 처리는 필요하지 않습니다.

관련 리소스

Overlay Checkout

page에서 checkout을 modal overlay로 열기

Inline Checkout

checkout을 page에 직접 embed

Mobile Integration

native mobile app에 checkout 통합

Webhooks

payment 및 subscription event 수신

Payment Methods

region별 지원 payment method

Subscriptions

recurring billing 및 subscription 관리
마지막 수정일 2026년 10월 8일