Skip to main content

Checkout Sessions

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

Payment Links

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

Webhooks

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

API Reference

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

사전 요구 사항

시작하기 전에 다음이 필요합니다:
  • Dodo Payments 계정
  • 하나 이상의 product. 대시보드의 Products에서 생성합니다. 가격이 0이 아닌 subscription product는 고객이 결제하는 통화의 subscription minimum을 충족해야 합니다: USD의 경우 $1.00입니다. USD, EUR, GBP 이외의 통화도 최소 $1.00 이상의 가치가 있어야 합니다. $0 subscription도 지원됩니다.
  • API key. Developer → API Keys에서 생성하고 DODO_PAYMENTS_API_KEY 환경 변수에 저장합니다. 개발 중에는 test mode로 key를 생성하세요. 이 페이지의 예제는 test mode를 사용하며 test mode key는 test mode에서만 작동합니다. Authentication을 참조하세요.
  • 사용 중인 언어의 SDK. Node.js SDK에는 Node.js 20 이상이 필요하고, Python SDK에는 Python 3.9 이상이 필요하며, Go SDK에는 Go 1.22 이상이 필요합니다. cURL 예제에는 SDK가 필요하지 않습니다.
webhook example에서도 standardwebhooks package를 사용합니다. npm install standardwebhooks로 설치하세요.

Integration 경로 선택

Overlay 및 inline checkout은 웹 페이지에서만 실행됩니다. native mobile app에서는 서버에서 checkout session을 생성한 다음 mobile checkout SDK를 사용해 해당 checkout_url를 여세요. coding agent가 이 integration을 대신 구축하도록 하려면 Agent Plugin을 설치하세요.

Checkout Sessions

안전한 호스팅 checkout 환경을 생성합니다. 서버에서 session을 생성한 다음 반환된 checkout_url로 고객을 redirect합니다.
각 checkout_url는 한 번만 작동하며 24시간 후 만료됩니다. 단, confirm: true를 전달하면 15분 후 만료됩니다. confirm: true를 사용하는 경우 모든 required field도 제공해야 합니다. 고객별, payment attempt별로 새 session을 생성하세요.

Checkout Session 생성

Checkout으로 Redirect

session을 생성한 후 고객을 checkout_url로 redirect합니다:
고급 customization은 전체 Checkout Sessions 가이드와 API Reference를 참조하세요.

오류 처리

request가 실패하면 API는 HTTP status code와 code 및 message가 포함된 JSON body를 반환합니다. message가 아니라 code를 기준으로 error handling을 분기하세요. 각 code의 원인과 해결 방법은 Error Codes를 참조하세요. 실패한 payment는 별도로 보고됩니다. payment의 status는 failed이고, error_code에서 이유를 확인할 수 있으며, payment.failed webhook을 받습니다. 재시도 여부를 결정하려면 Handle Payment Failures를 참조하세요. payment link는 product의 checkout을 여는 URL이므로 code를 작성하지 않고도 payment를 수집할 수 있습니다. query parameter로 고객 정보를 미리 입력하고 checkout form을 제어할 수 있습니다. 고객이 link를 열면 checkout은 parameter를 session에 저장하고 URL을 session parameter로 단축하므로 페이지를 새로 고침해도 해당 정보가 유지됩니다. static payment link는 한 번 생성하여 여러 번 공유하는 URL입니다. 기본 URL은 다음과 같습니다:
checkout을 customization하려면 query parameter를 추가하세요:
integer
기본값:"1"
구매할 item 수입니다.
string
필수
Payment links는 redirect_url를 사용합니다. Checkout Sessions API는 같은 용도로 return_url를 사용합니다.payment 후 redirect할 URL입니다. Dodo Payments는 payment 세부 정보를 query parameter로 추가합니다. 예: https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com. product에서 license key를 발급하는 경우 license_key parameter도 추가되며, 여러 key는 쉼표로 구분됩니다.
string
payment currency를 지정합니다. 기본값은 billing country의 currency입니다.
boolean
기본값:"true"
currency selector를 표시하거나 숨깁니다.
boolean
기본값:"true"
discounts section을 표시하거나 숨깁니다. 고객이 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
custom metadata field입니다. 예: metadata_orderId=123.

고객 정보 미리 입력

checkout을 간소화하려면 고객 field를 query parameter로 추가하세요:
string
고객의 전체 이름입니다(firstName 또는 lastName이 제공되면 무시됨).
string
고객의 이름입니다.
string
고객의 성입니다.
string
고객의 email address입니다.
string
고객의 country입니다(ISO 3166-1 alpha-2 code).
string
도로명 주소입니다.
string
도시입니다.
string
주 또는 도입니다.
string
우편번호 또는 ZIP code입니다.

Form field 비활성화

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

Webhooks

Webhooks는 payment가 성공하거나 실패했을 때 서버에 알려 주문을 처리할 수 있도록 합니다.

Webhook Endpoint 생성

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

수신할 Event

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

Currency 및 Billing Address

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

One-Click Repeat Purchase

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

관련 페이지

Checkout Sessions

고급 customization 옵션을 포함한 전체 가이드입니다.

Overlay Checkout

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

Inline Checkout

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

Subscription Integration

recurring billing을 설정합니다.

Webhook Event Guide

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

API Reference

Checkout Sessions API documentation입니다.
마지막 수정일 2026년 10월 8일