Skip to main content

Checkout Sessions

일회성 결제 및 구독을 위한 안전한 호스팅 checkout을 생성합니다.

Payment Links

코드 없이 결제를 수집할 수 있도록 URL을 공유합니다.

Webhooks

결제 이벤트를 수신하고 주문을 처리합니다.

API Reference

전체 endpoint 문서와 실시간 테스트를 제공합니다.

사전 요구 사항

시작하기 전에 다음이 필요합니다:
  • Dodo Payments 계정
  • 하나 이상의 product. 대시보드의 Products에서 생성하세요. 0이 아닌 가격의 subscription product는 가격을 $1 이상 또는 해당 통화로 이에 상응하는 금액으로 설정해야 합니다. $0 subscription도 지원됩니다.
  • API key. Developer → API Keys에서 생성하고 DODO_PAYMENTS_API_KEY environment variable에 저장하세요. 개발하는 동안에는 test mode로 key를 생성하세요. 이 페이지의 예제는 test mode를 사용하며 test mode key는 test mode에서만 작동합니다. Authentication을 참조하세요.

통합 경로 선택

Overlay checkout 및 inline checkout은 웹 페이지에서만 실행됩니다. 네이티브 모바일 앱에서는 서버에서 checkout session을 생성한 다음 mobile checkout SDK로 해당 checkout_url를 여세요. coding agent가 이 통합을 대신 구축하도록 하려면 Agent Plugin을 설치하세요.

Checkout Sessions

안전한 호스팅 checkout 환경을 생성합니다. 서버에서 session을 생성한 다음 반환된 checkout_url로 customer를 redirect합니다.
각 checkout_url는 한 번만 사용할 수 있으며 24시간 후 만료됩니다. confirm: true를 전달하면 15분 후 만료됩니다. confirm: true를 사용하면 모든 필수 field도 제공해야 합니다. 각 customer와 각 결제 시도마다 새 session을 생성하세요.

Checkout Session 생성

Checkout으로 redirect

session을 생성한 후 customer를 다음 checkout_url로 redirect합니다:
고급 사용자 설정은 전체 Checkout Sessions 가이드와 API Reference를 참조하세요.
payment link는 product의 checkout을 여는 URL이므로 코드를 작성하지 않고 결제를 수집할 수 있습니다. Query parameter는 customer 정보를 미리 입력하고 checkout form을 제어합니다. customer가 link를 열면 checkout은 parameter를 session에 저장하고 URL을 session parameter로 단축하므로 페이지를 새로 고침해도 해당 정보가 유지됩니다. static payment link는 한 번 생성하여 여러 번 공유하는 URL입니다. 기본 URL은 다음과 같습니다:
checkout을 사용자 지정하려면 query parameter를 추가하세요:
integer
기본값:"1"
구매할 item 수입니다.
string
필수
Payment links는 redirect_url를 사용합니다. Checkout Sessions API는 같은 용도로 return_url를 사용합니다.결제 후 redirect할 URL입니다. Dodo Payments는 결제 세부 정보를 query parameter로 추가합니다. 예: https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com. product가 license key를 발급하는 경우 license_key parameter도 추가되며, 여러 key는 쉼표로 구분됩니다.
string
결제 통화를 지정합니다. 기본값은 billing country의 통화입니다.
boolean
기본값:"true"
currency selector를 표시하거나 숨깁니다.
boolean
기본값:"true"
discounts section을 표시하거나 숨깁니다. customer가 coupon code를 입력하지 못하도록 하려면 false로 설정하세요.
number
청구 금액을 major currency unit으로 고정합니다. 예를 들어 12.5는 $12.50입니다. Pay What You Want product에서만 작동하며 product의 minimum price보다 낮으면 무시됩니다.
paymentAmount는 major currency unit을 사용합니다(12.5는 $12.50). Checkout Sessions API field인 product_cart[].amount는 smallest currency unit을 사용합니다(1250는 $12.50). Dynamic Pricing을 참조하세요.
string
사용자 지정 metadata field입니다. 예: metadata_orderId=123.

Customer 정보 미리 입력

checkout을 간소화하려면 customer field를 query parameter로 추가하세요:
string
Customer의 전체 이름입니다(firstName 또는 lastName이 제공되면 무시됨).
string
Customer의 이름입니다.
string
Customer의 성입니다.
string
Customer의 email address입니다.
string
Customer의 country입니다(ISO 3166-1 alpha-2 code).
string
Street address입니다.
string
City입니다.
string
State 또는 province입니다.
string
Postal 또는 ZIP code입니다.

Form field 비활성화

Customer가 미리 입력된 정보를 변경하지 못하게 하려면 값을 제공하고 해당 disable... flag를 true로 설정하여 field를 비활성화하세요:
field를 비활성화하면 실수로 변경되는 것을 방지하고 데이터 일관성을 보장할 수 있습니다.
POST /payments 및 POST /subscriptions endpoint는 deprecated되었습니다. 새로운 통합에는 대신 Checkout Sessions을 사용하세요.
dynamic payment links를 사용하는 기존 통합에서는 payment_link: true를 Create One-Time Payment 또는 Create Subscription에 전달하여 link를 생성하세요. 아래 예제는 일회성 payment link를 생성합니다. subscription은 Subscription Integration Guide를 참조하세요.

Webhooks

Webhooks는 결제가 성공하거나 실패했을 때 서버에 알려 주므로 주문을 처리할 수 있습니다.

Webhook Endpoint 생성

대시보드에서 Developer → Webhooks로 이동하여 endpoint URL을 추가하세요. endpoint의 signing secret을 DODO_PAYMENTS_WEBHOOK_KEY environment variable에 복사하세요. 다음은 Next.js를 사용한 예시입니다:
app/api/webhooks/dodo/route.ts
저희 webhook 구현은 Standard Webhooks specification을 따릅니다.

수신할 이벤트

최소한 일회성 payment flow에서는 다음 이벤트를 수신하세요:
항상 browser redirect가 아니라 webhook의 payment.succeeded에서 주문을 처리하세요. customer가 tab을 닫으면 redirect를 놓칠 수 있지만 webhook은 acknowledge될 때까지 재시도됩니다.
license key가 있는 product를 판매하는 경우 license_key.created도 처리하세요. subscription, entitlement, credit, recovery 및 dunning event를 포함한 전체 event 목록은 Webhook Event Guide를 참조하세요. 완전한 Next.js 및 TypeScript 예제는 demo repository와 live deployment를 참조하세요.

통화 및 Billing Address

특정 통화로 청구하려면 checkout session을 생성할 때 billing_currency 및 billing_address.country를 전달하세요. 생략하면 Adaptive Currency가 customer의 IP address에서 통화와 country를 선택하므로 의도한 통화와 다를 수 있습니다. Pay What You Want 금액은 product의 base currency로 표시되며 USD, GBP 또는 EUR이어야 합니다. 다른 통화로 고정 금액을 수집하려면 실시간 환율로 base price를 변환하는 Adaptive Currency 또는 통화별 고정 가격을 설정하는 Localized Pricing을 사용하세요. Localized Pricing은 Pay What You Want에서 작동하지 않습니다.

원클릭 반복 구매

저장된 payment method로 returning customer에게 청구하려면 해당 method의 payment_method_id를 confirm: true와 함께 전달하세요. payment_method_id는 confirm가 true인 경우에만 허용되며, 기존 customer의 customer_id도 전달해야 합니다. confirm가 true이므로 완전한 billing_address도 전달해야 합니다. session은 저장된 payment method로 직접 청구하므로 checkout_url를 반환하지 않습니다. 결제 성공 여부를 확인하려면 webhooks를 사용하세요.

관련 페이지

Checkout Sessions

고급 사용자 설정 옵션을 포함한 전체 가이드입니다.

Overlay Checkout

페이지에 checkout을 modal overlay로 삽입합니다.

Inline Checkout

페이지 레이아웃에 checkout을 직접 삽입합니다.

Subscription Integration

recurring billing을 설정합니다.

Webhook Event Guide

모든 webhook event의 전체 목록입니다.

API Reference

Checkout Sessions API 문서입니다.
마지막 수정일 2026년 9월 26일