Checkout Sessions
Payment Links
Webhooks
API Reference
사전 요구 사항
시작하기 전에 다음이 필요합니다:- 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은 다음과 같습니다: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보다 낮으면 무시됩니다.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를 비활성화하세요:
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를 사용하세요.