Skip to main content

사전 요구 사항

Dodo Payments API를 통합하려면 다음이 필요합니다:
  • Dodo Payments merchant 계정
  • 대시보드의 API Credentials (API key 및 webhook secret key)

대시보드 설정

  1. Dodo Payments Dashboard로 이동합니다.
  2. 제품을 생성합니다(일회성 결제 또는 구독). 구독 제품의 가격은 최소 $1(또는 선택한 통화로 이에 상응하는 금액)이어야 합니다. 이 최소 금액보다 낮은 금액은 지원되지 않습니다.
  3. API key를 생성합니다:
    • Developer > API로 이동합니다.
    • 자세한 가이드
    • 환경 변수 DODO_PAYMENTS_API_KEY에 있는 API key를 복사합니다.
  4. webhooks를 구성합니다:
    • Developer > Webhooks로 이동합니다.
    • 결제 알림을 위한 webhook URL을 생성합니다.
    • 환경 변수에 있는 webhook secret key를 복사합니다.

통합

사용 사례에 적합한 통합 경로를 선택하세요:
  • Checkout Sessions(권장): 대부분의 통합에 가장 적합합니다. 서버에서 세션을 생성한 후 고객을 안전하게 호스팅된 결제 페이지로 리디렉션합니다.
  • Overlay Checkout: 사이트에서 결제를 모달 오버레이로 열어 페이지 내 환경을 제공해야 할 때 사용합니다.
  • Inline Checkout: 완전히 통합되고 브랜드가 적용된 결제 환경을 위해 결제 페이지를 레이아웃에 직접 삽입합니다.
  • Static Payment Links: 빠르게 결제를 수집할 수 있는 코드 없는 즉시 공유 가능한 URL입니다.
  • Dynamic Payment Links: 프로그래밍 방식으로 생성되는 링크입니다. 하지만 더 높은 유연성을 제공하는 Checkout Sessions 사용을 권장합니다.
  • Mobile Checkout SDKs: 네이티브 Android, iOS, React Native 및 Flutter 앱용입니다. 위와 같이 서버에서 세션을 생성한 다음 checkout_url를 SDK에 전달합니다.
Overlay 및 Inline Checkout은 브라우저 전용입니다. 웹 페이지에 결제 페이지를 삽입합니다. 네이티브 모바일 앱을 개발하는 경우 서버에서 결제 세션을 생성하고 대신 Mobile Checkout SDKs를 사용해 엽니다.

1. Checkout Sessions

Checkout Sessions를 사용하면 일회성 결제 또는 구독을 위한 안전한 호스팅 결제 환경을 만들 수 있습니다. 서버에서 세션을 생성한 다음 반환된 checkout_url로 고객을 리디렉션합니다.
Checkout 세션은 기본적으로 24시간 동안 유효합니다. confirm=true를 전달하면 세션은 15분 동안 유효하며 모든 필수 필드를 제공해야 합니다.
1

Create a checkout session

원하는 SDK를 선택하거나 REST API를 호출합니다.
2

Redirect customer to checkout

세션을 생성한 후 checkout_url로 리디렉션하여 호스팅 결제 흐름을 시작합니다.
결제를 가장 빠르고 안정적으로 시작하려면 Checkout Sessions를 사용하세요. 고급 사용자 지정이 필요한 경우 전체 Checkout Sessions 가이드API Reference를 참조하세요.

2. Overlay Checkout

원활한 페이지 내 결제 환경을 위해 고객이 웹사이트를 떠나지 않고 결제를 완료할 수 있는 Overlay Checkout 통합을 살펴보세요.

3. Inline Checkout

페이지에 직접 삽입되는 완전히 통합된 결제 환경을 제공하려면 Inline Checkout 통합을 사용하세요. 이를 통해 사용자 지정 주문 요약을 만들고 결제 레이아웃을 완전히 제어할 수 있으며, Dodo Payments가 결제 수집을 안전하게 처리합니다. Static payment links를 사용하면 간단한 URL을 공유하여 빠르게 결제를 받을 수 있습니다. query parameters를 전달하여 고객 정보를 미리 입력하고, 양식 필드를 제어하며, 사용자 지정 메타데이터를 추가하는 방식으로 결제 환경을 사용자 지정할 수 있습니다.
1

Construct your payment link

기본 URL로 시작한 다음 제품 ID를 추가합니다:
2

Add core parameters

필수 query parameters를 포함합니다:
  • integer
    기본값:"1"
    구매할 항목 수입니다.
  • string
    필수
    결제 완료 후 리디렉션할 URL입니다.
리디렉션 URL에는 query parameters로 결제 세부 정보가 포함됩니다. 예:
https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com

제품에 라이선스 키가 활성화되어 있으면 license_key parameter도 추가됩니다(여러 키의 경우 쉼표로 구분):
https://example.com/?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com
3

Pre-fill customer information (optional)

결제를 간소화하려면 고객 또는 청구 필드를 query parameters로 추가합니다.
  • string
    고객의 전체 이름입니다(firstName 또는 lastName이 제공되면 무시됨).
  • string
    고객의 이름입니다.
  • string
    고객의 성입니다.
  • string
    고객의 이메일 주소입니다.
  • string
    고객의 국가입니다.
  • string
    도로명 주소입니다.
  • string
    도시입니다.
  • string
    주 또는 도입니다.
  • string
    우편번호/ZIP 코드입니다.
  • boolean
    true 또는 false
4

Control form fields (optional)

특정 필드를 비활성화하여 고객이 읽기 전용으로 사용하도록 설정할 수 있습니다. 이는 이미 고객 정보(예: 로그인한 사용자)를 보유하고 있을 때 유용합니다.
필드를 비활성화하려면 값을 제공하고 해당 disable… flag를 true로 설정합니다:
필드를 비활성화하면 실수로 변경되는 것을 방지하고 데이터 일관성을 유지할 수 있습니다.
showDiscounts=false를 설정하면 결제 양식의 할인 섹션이 비활성화되고 숨겨집니다. 결제 중 고객이 coupon 또는 promo code를 입력하지 못하게 하려는 경우 사용하세요.
5

Add advanced controls (optional)

  • string
    결제 통화를 지정합니다. 기본값은 청구 국가의 통화입니다.
  • boolean
    기본값:"true"
    통화 선택기를 표시하거나 숨깁니다.
  • integer
    센트 단위의 금액입니다(Pay What You Want 가격 책정 전용).
  • string
    사용자 지정 메타데이터 필드입니다(예: metadata_orderId=123).
6

Share the link

완성된 payment link를 고객에게 보냅니다. 고객이 방문하면 모든 query parameters가 수집되어 session ID와 함께 저장됩니다. 그런 다음 URL은 session parameter만 포함하도록 단순화됩니다(예: ?session=sess_1a2b3c4d). 저장된 정보는 페이지를 새로 고침해도 유지되며 결제 과정 전체에서 액세스할 수 있습니다.
이제 고객의 checkout 경험은 전달한 parameters에 따라 간소화되고 개인화됩니다.
대부분의 사용 사례에서는 Checkout Sessions를 사용하세요. 더 높은 유연성과 제어 기능을 제공합니다.
고객 정보와 함께 API 호출 또는 당사 SDK를 통해 생성합니다. 예시는 다음과 같습니다: Dynamic payment links를 생성하는 API는 두 가지입니다: 아래 가이드는 일회성 payment link 생성에 관한 내용입니다. 구독 통합에 대한 자세한 지침은 Subscription Integration Guide를 참조하세요.
payment link를 받으려면 payment_link = true를 전달해야 합니다.
payment link를 생성한 후 고객을 리디렉션하여 결제를 완료하도록 합니다.

Webhooks 구현

결제 알림을 수신할 API endpoint를 설정합니다. 다음은 Next.js를 사용한 예시입니다:
당사의 webhook 구현은 Standard Webhooks 사양을 따릅니다. webhook type definitions는 Webhook Event Guide를 참조하세요.

수신할 이벤트

payload.type를 활성화하고 일회성 결제 흐름과 관련된 이벤트를 처리합니다. 최소한 다음 이벤트를 수신해야 합니다:
항상 브라우저 리디렉션이 아니라 webhook의 payment.succeeded에서 주문을 이행하세요. 고객이 탭을 닫으면 리디렉션을 놓칠 수 있지만 webhook은 승인될 때까지 재시도됩니다.
라이선스 키가 포함된 디지털 제품을 판매하는 경우 license_key.created도 처리하세요. 구독, entitlement, credit, recovery 및 dunning 이벤트를 포함한 전체 이벤트 목록은 Webhook Event Guide를 참조하세요. Next.js 및 TypeScript를 사용한 데모 구현 프로젝트는 GitHub에서 확인할 수 있습니다. 실제 구현은 여기에서 확인할 수 있습니다.

Checkout 및 통화에 대해 알아야 할 주요 사항

Dynamic(Pay-What-You-Want) 금액은 임의의 현지 통화가 아니라 제품의 기본 통화로 표시됩니다. 기본 통화는 USD, INR, GBP 및 EUR로 제한됩니다. 다른 통화(예: PHP)로 고정 금액을 받으려면 직접 전달할 수 없습니다. 대신 Adaptive Pricing(실시간 FX로 기본 금액 변환) 또는 Localized Pricing(통화별 고정 가격이지만 Pay-What-You-Want와 호환되지 않음)을 사용하세요.
통화를 명시적으로 고정하세요. checkout session에 billing_currencybilling_address.country를 전달합니다. 생략하면 고객의 IP에서 통화와 국가가 감지되므로(Adaptive Currency) 의도한 청구 내용과 일치하지 않을 수 있습니다.
Checkout 세션은 24시간 후 만료됩니다(confirm: true인 경우 15분). 또한 각 checkout_url한 번만 사용할 수 있습니다. 링크를 재사용하지 말고 고객 및 결제 시도마다 새 세션을 생성하세요.
반복 구매 원클릭 결제. 저장된 결제 수단이 있는 기존 고객의 경우 confirm: true와 함께 payment_method_id를 전달하면 결제 수단 선택을 완전히 건너뛰고 즉시 청구할 수 있습니다.

관련 API Reference

Create Checkout Session

일회성 결제 및 구독을 위한 안전한 호스팅 checkout session 생성 API reference

Create Payment Link

프로그래밍 방식으로 dynamic payment links를 생성하는 API reference
마지막 수정일 2026년 7월 31일