API 레퍼런스 - Dodo Payments Documentation

SDKs & Libraries

TypeScript, Python, Go, PHP, Java, Kotlin, C#, Ruby 및 Rust용 공식 백엔드 SDK입니다. 이러한 라이브러리는 인증, 직렬화 및 오류 처리를 담당하므로 통합에 집중할 수 있습니다.

Mobile Checkout SDKs

Android, iOS, React Native 및 Flutter 앱에서 Dodo의 호스팅 체크아웃을 열고 한 번의 호출로 타입이 지정된 결과를 받으세요. 이러한 SDK에는 API 키가 포함되지 않습니다.

환경 URL

테스트 모드: https://test.dodopayments.com
라이브 모드: https://live.dodopayments.com

Test Mode와 Live Mode에 대해 자세히 알아보세요.

인증

API 요청에는 API 키가 필요합니다. 단, 라이선스 활성화, 라이선스 검증, 라이선스 비활성화와 같은 일부 공개 엔드포인트는 예외입니다. 대시보드에서 API 키를 생성하고 모든 요청의 Authorization 헤더에 포함하세요.

Generate an API Key

대시보드에서 Developer → API Keys로 이동한 다음 Add API Key를 선택하세요. 호출하려는 모드에서 키를 생성하세요. 테스트 모드 키는 https://test.dodopayments.com에서만 작동하고, 라이브 모드 키는 https://live.dodopayments.com에서만 작동합니다. 키에 설명이 포함된 이름을 지정하고 액세스 수준을 선택하세요.

Enable write access 선택됨(기본값): 모든 API 작업에 대한 전체 읽기 및 쓰기 권한입니다.
Enable write access 선택되지 않음: 읽기 전용 액세스입니다. 데이터를 가져올 수 있지만(결제, 구독, 고객, 제품), 리소스를 생성하거나 수정할 수는 없습니다.

분석 도구나 대시보드 통합처럼 데이터를 보기만 하면 되는 통합에서는 Enable write access 선택을 해제하세요.

Store Your Key Securely

키를 즉시 복사하세요. 다시 표시되지 않습니다. DODO_PAYMENTS_API_KEY와 같은 환경 변수에 저장하세요.

Authenticate Requests

모든 요청의 Authorization 헤더에 API 키를 포함하세요:

Authorization: Bearer YOUR_API_KEY

클라이언트 측 코드, 공개 리포지토리 또는 버전 관리 시스템에 API 키를 절대 노출하지 마세요.

Response 형식

성공한 요청은 JSON 본문과 함께 200 또는 201를 반환하거나, 본문 없이 204를 반환합니다. 오류가 발생하면 JSON 본문에 code 및 message가 포함된 4xx 또는 5xx 상태를 반환합니다.

{
  "payment_id": "pay_gr4RizvMOXFJ6xca3y2tU",
  "status": "succeeded",
  "total_amount": 2999,
  "currency": "USD",
  "created_at": "2024-01-15T10:30:00Z"
}

{
  "code": "INVALID_REQUEST_BODY",
  "message": "Your request body is invalid. Please check your request headers and object."
}

Rate Limits

API는 초당 버스트 제한과 분당 지속 제한이라는 두 가지 제한을 동시에 적용합니다. 제한은 비즈니스 전체에 적용되며 모든 API 키에 걸쳐 공유됩니다. 또한 비즈니스의 rate limit tier에 따라 달라집니다.

기본 티어

기간	제한
초당(버스트)	40 requests
분당(지속)	240 requests

상위 티어

API 요구 사항이 증가한 비즈니스는 더 높은 rate limit으로 업그레이드할 수 있습니다:

티어	버스트(초당)	지속(분당)
기본값	40	240
Tier 1	100	1,000
Tier 2	500	5,000

rate limit tier를 업그레이드하려면 support@dodopayments.com으로 이메일을 보내세요.

인증되지 않은 요청

유효한 API 키가 없는 요청에는 IP 주소별 rate limit이 적용됩니다:

기간	제한
초당(버스트)	20 requests
분당(지속)	100 requests

Rate Limit 헤더

응답에는 현재 사용량을 보여 주는 헤더가 포함됩니다:

X-RateLimit-Limit — 현재 기간에 허용되는 최대 요청 수입니다.
X-RateLimit-Remaining — 제한에 도달하기 전까지 남은 요청 수입니다.
X-RateLimit-Reset — 현재 기간이 재설정될 때까지 남은 시간(초)입니다.

제한을 초과하면 API는 429 Too Many Requests를 반환합니다. 재시도 로직에 지수 백오프를 구현하세요.

오류 처리

오류의 의미와 해결 방법을 확인하려면 오류 코드 및 거래 실패 페이지를 참조하세요.

Error Codes

모든 오류 코드와 그 의미를 확인할 수 있습니다.

Transaction Failures

일반적인 거래 문제와 처리 방법을 확인할 수 있습니다.

웹훅

결제, 구독 및 기타 이벤트가 발생할 때 실시간 알림을 받으세요. 대시보드에서 웹훅을 설정하고 통합에 필요한 이벤트를 처리하세요.

Webhook Guide

웹훅을 설정하고, 이벤트를 처리하며, 서명을 검증하세요.

통합 가이드

첫 번째 통합을 구축하려면 다음 가이드 중 하나로 시작하세요:

One-time Payments

체크아웃 세션과 결제 링크를 생성하고 결제를 처리하세요.

Subscriptions

반복 청구를 설정하고, 플랜을 관리하며, 수명 주기 이벤트를 처리하세요.

Usage-Based Billing

사용량을 측정하고 소비량을 기준으로 고객에게 요금을 청구하세요.

Checkout Sessions

안전한 호스팅 체크아웃 환경을 구축하세요.

SDKs & Libraries

Mobile Checkout SDKs

​환경 URL

​인증

​Response 형식

​Rate Limits

​기본 티어

​상위 티어

​인증되지 않은 요청

​Rate Limit 헤더

​오류 처리

Error Codes

Transaction Failures

​웹훅

Webhook Guide

​통합 가이드

One-time Payments

Subscriptions

Usage-Based Billing

Checkout Sessions

환경 URL

인증

Response 형식

Rate Limits

기본 티어

상위 티어

인증되지 않은 요청

Rate Limit 헤더

오류 처리

웹훅

통합 가이드