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가 필요하지 않습니다.
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 Session 생성
- Node.js SDK
- Python SDK
- cURL
Checkout으로 Redirect
session을 생성한 후 고객을checkout_url로 redirect합니다:
오류 처리
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 Links
payment link는 product의 checkout을 여는 URL이므로 code를 작성하지 않고도 payment를 수집할 수 있습니다. query parameter로 고객 정보를 미리 입력하고 checkout form을 제어할 수 있습니다. 고객이 link를 열면 checkout은 parameter를 session에 저장하고 URL을session parameter로 단축하므로 페이지를 새로 고침해도 해당 정보가 유지됩니다.
Static Payment Links
static payment link는 한 번 생성하여 여러 번 공유하는 URL입니다. 기본 URL은 다음과 같습니다: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는 쉼표로 구분됩니다.청구 금액을 major currency unit으로 고정합니다. 예를 들어
12.5는 $12.50입니다. Pay What You Want product에서만 작동하며 product의 minimum price보다 낮으면 무시됩니다.고객 정보 미리 입력
checkout을 간소화하려면 고객 field를 query parameter로 추가하세요:Form field 비활성화
고객이 미리 입력된 정보를 변경하지 못하도록 하려면 해당 value를 제공하고 관련disable... flag를 true로 설정하여 field를 비활성화하세요:
Static Payment Link 예제
Dynamic Payment Links (Deprecated)
dynamic payment link를 사용하는 기존 integration에서는payment_link: true를 Create One-Time Payment 또는 Create Subscription에 전달하여 link를 생성하세요. 아래 예제에서는 one-time payment link를 생성합니다. subscription은 Subscription Integration Guide를 참조하세요.
- Node.js SDK
- Python SDK
- Go SDK
Webhooks
Webhooks는 payment가 성공하거나 실패했을 때 서버에 알려 주문을 처리할 수 있도록 합니다.Webhook Endpoint 생성
대시보드에서 Developer → Webhooks로 이동하여 endpoint URL을 추가하세요. endpoint의 signing secret을DODO_PAYMENTS_WEBHOOK_KEY 환경 변수에 복사합니다.
다음은 Next.js를 사용한 예제입니다:
app/api/webhooks/dodo/route.ts
수신할 Event
최소한 one-time payment flow에서는 다음 event를 수신하세요:
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입니다.