Documentation Index
Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
Use this file to discover all available pages before exploring further.
새로운 기능
1. 권한
Dodo Payments는 이제 통합된 Entitlements와 함께 제공되어 모든 이행 통합을 위한 자동 배송을 지원합니다. 단 하나의 제품으로도 여러 권한을 성공적인 구매 또는 활성 구독마다 전달할 수 있습니다.
다섯 가지 새로운 플랫폼 통합
이전까지 Dodo Payments는 라이센스 키와 디지털 파일을 자동으로 구매 시 제공했습니다. 권한은 그 범위를 다섯 가지 추가 플랫폼으로 확장하여, 고객이 결제를 완료하는 즉시 커뮤니티, 코드 또는 콘텐츠에 접근할 수 있게 합니다. 이는 귀하가 직접 이행하지 않아도 됩니다:
| 통합 | 무엇을 제공합니까 | 폐지 동작 |
|---|
| Discord | 고객이 OAuth를 완료한 후 Discord 서버에서 선택된 역할을 할당 | 취소/환불 시 역할 제거 |
| GitHub | 고객을 선택한 권한 수준으로 개인 레포지토리의 협력자로 추가 | 취소/환불 시 협력자 제거 |
| Telegram | Telegram 봇을 통해 개인 채팅이나 채널에 일회성 초대 링크 발급 | 취소/환불 시 채팅에서 고객을 내보냄 |
| Framer | 접근 코드로 제한된 Framer 템플릿 리믹스 링크 잠금 해제 | 취소/환불 시 접근 코드 비활성화 |
| Notion | 고객이 OAuth로 인증한 후 Notion 템플릿 페이지를 고객의 작업 공간에 복제 | 취소/환불 시 전달된 페이지를 아카이브 |
이들은 기존 라이센스 키(활성화 제한과 만료가 있는 고유 키)와 디지털 파일(eBook, 템플릿, 미디어를 위한 presigned 다운로드 URL) 통합에 합류하여, 이제 같은 승인 수명주기를 통해 관리됩니다.
기본 제공 기능
| 기능 | 설명 |
|---|
| 재사용 가능한 템플릿 | 권한을 한 번 정의(활성화 제한, 파일 번들, Discord 역할, 레포 권한 등)하고 이를 아무 제품에나 연결 |
| 자동 승인 | payment.succeeded와 subscription.active에서 발급되며, 갱신 및 재활성화 시에도 일관성 유지 |
| 수명주기 인식 취소 | 다음 시점에 취소됨: subscription.cancelled, subscription.on_hold, subscription.expired, refund.succeeded, subscription.plan_changed, 또는 수동 API/대시보드 취소 — 인라인 코드 PLACEHOLDER_91342c97f9c7ae55_END와 함께 |
| OAuth + 플랫폼 직접 흐름 | Discord, GitHub, Notion에 대한 구독자 동의를 위한 OAuth; Telegram, Framer, 그리고 디지털 파일에 직접 플랫폼 호출 |
| 드리프트 감지 | Discord 역할, GitHub 협력자 또는 Notion 페이지가 플랫폼 수준에서 동기화되지 않을 때 이를 감지하고 revocation_reason: platform_external로 취소 |
| At-rest 암호화 | 모든 플랫폼 토큰(OAuth, 봇, 앱 설치)이 AES-256-GCM으로 저장됨 |
웹훅
모든 승인에 대해 네 가지 새로운 수명주기 이벤트가 실행됩니다:
| 이벤트 | 언제 실행되나요 |
|---|
entitlement_grant.created | 고객을 위한 새 승인이 생성될 때 |
entitlement_grant.delivered | 고객 접근이 제공될 때 |
entitlement_grant.failed | 전달을 완료할 수 없을 때; error_code 및 error_message를 검사 |
entitlement_grant.revoked | 접근이 철회될 때; revocation_reason 검사 |
새로운 통합에 대해서는 entitlement_grant.delivered를 수신해 주시기 바랍니다. 결제 성공이 곧 전달 완료를 의미하지는 않습니다. 특히 OAuth 기반 통합의 경우가 그렇습니다.
자세히 알아보기: Entitlements | Entitlement Grant Webhooks
2. 고객 포털에서 구독 취소 이유
고객이 고객 포털에서 구독을 취소할 때, 이제 확인을 완료하기 전에 왜 취소하는지를 공유하도록 요청을 받습니다. 수집된 이유는 구독에 cancellation_feedback로 저장되어 API 및 웹훅 페이로드에서 표시되며, 대시보드에서 손쉽게 이탈 패턴을 찾을 수 있게 합니다.
이유 옵션
| 값 | 고객 대상 라벨 |
|---|
too_expensive | 비쌈 |
missing_features | 기능 부족 |
switched_service | 다른 서비스로 전환 |
unused | 충분히 사용하지 않음 |
customer_service | 나쁜 고객 서비스 |
low_quality | 낮은 품질 |
too_complex | 너무 복잡함 |
other | 기타 |
표시되는 곳
- 구독 객체: 새
cancellation_feedback 필드(위 값 중 하나) 및 cancellation_comment(선택적 자유 텍스트), 고객이 취소할 때 채워짐
subscription.cancelled 웹훅: 두 필드 모두 페이로드에 포함됨
- API: 프로그램적으로 취소를 예약하거나 실행할 때
PATCH /subscriptions/{id}에 cancellation_feedback 및 cancellation_comment 전달
// Reading the captured feedback
const subscription = await client.subscriptions.retrieve('sub_123');
console.log(subscription.cancellation_feedback); // e.g., "too_expensive"
console.log(subscription.cancellation_comment); // e.g., "Switching to a competitor"
Subscription Dunning과 함께 cancellation_feedback를 결합하여 이탈 후 복귀 이메일을 맞춤화할 수 있습니다. 예: too_expensive 취소자에게 할인 코드를 보내고 missing_features 취소자에게 “누락된 것이 무엇인가요?” 설문조사를 보내세요.
자세히 알아보기: 고객 포털 | 구독 웹훅
3. INR E-명령의 구성 가능한 최소 금액
인도 카드의 반복 구독에서 INR e-명령의 최소 금액을 이제 구성할 수 있습니다. 이전에는 ₹15,000 미만의 모든 인도 카드 구독이 고정된 ₹15,000 주문형 명령을 사용했습니다. 이제 거래자 수준에서 이 최소 금액을 재정의할 수 있으며, 필요시 각 체크아웃 세션 또는 구독별로 구성할 수 있습니다.
고객의 은행에 등록된 명령 금액은 max(mandate_min_amount_inr_paise, billing_amount)이며, 이 값은 고객이 본인 계정에 접속할 때 인증 최고 한도로 작용합니다.
// Per-subscription override
const subscription = await client.subscriptions.create({
product_id: 'prod_inr_monthly',
customer: { email: 'customer@example.in' },
billing: { country: 'IN' /* ... */ },
mandate_min_amount_inr_paise: 2_000_000 // ₹20,000 ceiling for this subscription
});
// Or via a checkout session
const session = await client.checkoutSessions.create({
product_cart: [{ product_id: 'prod_inr_monthly', quantity: 1 }],
mandate_min_amount_inr_paise: 2_000_000,
return_url: 'https://yoursite.com/return'
});
해결 우선 순위
- 요청 시 재정의(
mandate_min_amount_inr_paise 체크아웃 세션, 결제 또는 구독 시)
- 비즈니스 설정의 거래자 수준 설정
- 시스템 기본 ₩15,000(1,500,000 paise)
| 필드 | 유형 | 범위 | 적용 대상 |
|---|
mandate_min_amount_inr_paise | integer(INR 파이즈) | >= 1 | 비 Airwallex 커넥터에서의 인도 카드 INR 구독 |
이 설정은 인도에 발행된 카드(Visa, Mastercard, RuPay)의 INR 구독에 대해 등록된 e-명령에만 영향을 미칩니다. UPI 구독은 자체 AutoPay 플로우를 따르며 영향을 받지 않습니다.
자세히 알아보기: 인도 결제 수단 | RBI 명령이 있는 구독
4. 적응형 통화 수수료 포함 비즈니스 설정
적응형 통화는 고객이 현지 통화로 결제할 수 있도록 하는 기능입니다. 기본적으로 2-4% 적응형 통화 수수료는 고객이 부담하며 귀하의 표시된 가격에 추가됩니다. 새로운 수수료 포함 설정을 사용하면 이를 반대로 전환하여 표시된 가격을 변경하지 않고 수수료를 귀하가 부담할 수 있습니다.
구성 위치
설정 → 비즈니스로 이동하여 적응형 가격 책정이 활성화되어 있는지 확인하고, 적응형 통화 섹션에서 수수료 포함을 토글하세요.
요청별 재정의
개별 체크아웃, 결제 및 주문형 구독의 경우 adaptive_currency_fees_inclusive 부울을 사용하여 상인 기본값을 재정의할 수도 있습니다:
const session = await client.checkoutSessions.create({
product_cart: [{ product_id: 'prod_abc', quantity: 1 }],
adaptive_currency_fees_inclusive: true, // override business default
return_url: 'https://yoursite.com/return'
});
| 모드 | 고객이 보는 것 | 상인 정산 |
|---|
| 독점(기본) | 현지 가격 + 2–4% 수수료 | 전체 기본 가격 |
| 포함됨 | 현지 가격(변경 없음) | 기본 가격에서 2–4% 수수료를 뺀 금액 |
INR → INR 거래는 비즈니스 설정이나 요청별 재정의에 관계없이 항상 포함된 것으로 처리됩니다.
자세히 알아보기: 적응형 통화
5. Dodo Payments 데스크탑 앱
정식 Dodo Payments 데스크탑 앱이 macOS, Windows, Linux용으로 출시되었습니다. 이제 빠르고 네이티브한 앱으로 결제 대시보드를 실행하세요. 브라우저 탭은 필요 없습니다.
| 플랫폼 | 다운로드 |
|---|
| macOS(Apple 실리콘) | Dodo.Payments_<version>_aarch64.dmg |
| macOS(Intel) | Dodo.Payments_<version>_x64.dmg |
| Windows | Dodo.Payments_<version>_x64-setup.exe (또는 .msi) |
| Linux(Debian/Ubuntu) | Dodo.Payments_<version>_amd64.deb |
| Linux(Fedora/RHEL) | Dodo.Payments-<version>-1.x86_64.rpm |
| Linux(AppImage, 자동 업데이트) | Dodo.Payments_<version>_amd64.AppImage |
내부 구성 요소
- 작고 네이티브 바이너리 — 시스템의 네이티브 웹뷰에서 Tauri로 빌드, 총 약 5MB(Chromium 번들되지 않음)
- 서명 및 공인 — macOS 빌드는 Apple 개발자 ID로 서명되고 공인되어 Gatekeeper 경고가 없음
- 자동 업데이트 — 4시간마다 체크하여 GitHub 릴리즈에서 서명된 업데이트를 자동으로 적용(macOS, Windows, Linux AppImage에서 작동)
- 시스템 트레이 + 메뉴 바 — macOS에서 트레이로 숨기기, 파일/편집/보기/도움말 메뉴에 키보드 단축키 포함(
⌘⇧H 대시보드로 이동, ⌘L 현재 URL 복사, ⌘⌥I 개발자 도구)
- 딥-링크 지원 — 매직 링크 인증 링크가 앱에서 바로 열림
- 멀티 윈도우 — 여러 대시보드를 나란히 열 수 있음
6. 안정적인 코인 결제(USDC, USDP, USDG)
USD 정산을 통해 전 세계적으로 안정적인 코인 결제를 수락하세요. 고객은 선택한 네트워크의 안정적인 코인 지갑에서 결제하고 귀하는 암호 화폐 변동에 대한 노출 없이, 충전취소 없이, 고객 쪽에서 은행 인프라가 필요 없이 피아트 USD를 받습니다.
지원되는 통화와 네트워크
| 안정적 코인 | 네트워크 |
|---|
| USDC | 이더리움, 솔라나, 폴리곤, 베이스 |
| USDP | 이더리움, 솔라나 |
| USDG | 이더리움 |
범위
| 세부 사항 | 값 |
|---|
| 청구 통화 | USD |
| 지원 국가 | 글로벌 (인도 제외) |
| 구독 | 지원되지 않음(일회성 결제만) |
| 최소 금액 | $0.50 |
| 정산 | USD |
구성 방법
체크아웃 세션을 만들 때 allowed_payment_method_types에 crypto를 전달하세요:
const session = await client.checkoutSessions.create({
product_cart: [{ product_id: 'prod_123', quantity: 1 }],
allowed_payment_method_types: ['crypto', 'credit', 'debit'],
return_url: 'https://example.com/success'
});
고객에게 지갑 주소와 QR 코드가 표시되고, 실시간 환율로 계산된 안정적인 코인 금액이 표시됩니다. 블록체인이 거래를 확인하면 payment.succeeded 웹훅이 실행되고 고객이 성공 페이지로 리디렉션됩니다.
안정적인 코인 결제는 설계상 취소할 수 없습니다. 항상 고객에게 안정적인 코인 지갑이 없는 경우에 대처할 수 있도록 credit 및 debit를 제공하는 것을 권장합니다.
자세히 알아보기: 안정적 코인 결제
7. 기존 라이센스 키 가져오기
라이센스 키 생성 API를 사용하여 다른 시스템의 **라이센스 키를 Dodo Payments로 가져올 수 있습니다. 이는 외부 라이센스 키 제공 업체로부터의 마찰 없는 마이그레이션을 가능하게 하여 기존 고객이 키를 다시 발급하지 않고도 Dodo Payments에 대해 활성화, 검증 및 비활성화할 수 있습니다.
const licenseKey = await client.licenseKeys.create({
customer_id: 'cus_abc123',
product_id: 'prod_456',
key: 'YOUR-EXISTING-LICENSE-KEY',
activations_limit: 5,
expires_at: '2026-12-31T23:59:59Z',
});
가져온 키는 source: "import"로 태그가 지정됩니다. (결제 시 자동 생성된 키의 경우 source: "auto"로 태그) 따라서 GET /license_keys를 쿼리할 때 마이그레이션된 인벤토리를 자연적으로 발행된 키와 구별할 수 있습니다. 가져온 키의 payment_id는 null입니다. 왜냐하면 이들은 Dodo Payments 거래와 연결되지 않기 때문입니다.
API를 통해 생성되거나 업데이트된 라이센스 키는 고객에게 이메일 알림을 트리거하지 않습니다. 가져온 키에 대해 고객에게 알리는 필요가 있다면, 귀하의 애플리케이션에서 별도로 처리해야 합니다.
Polar.sh 또는 Lemon Squeezy에서 마이그레이션 중이신가요? dodo-migrate CLI는 제품, 고객, 할인 및 라이센스 키를 단일 명령으로 대량 가져오기를 자동화합니다.
자세히 알아보기: 라이센스 키 | 라이센스 키 생성 API
8. 체크아웃 세션을 위한 require_phone_number
체크아웃 세션을 생성할 때 feature_flags.require_phone_number: true를 설정하여 고객이 체크아웃 중에 전화번호를 제공해야 하도록 강제할 수 있습니다. 전화번호는 체크아웃 양식의 필수 필드가 되며, 고객이 빈칸으로 남기면 “전화번호는 필수입니다”라는 양식 검증이 표시됩니다.
const session = await client.checkoutSessions.create({
product_cart: [{ product_id: 'prod_abc', quantity: 1 }],
feature_flags: {
allow_phone_number_collection: true,
require_phone_number: true
},
return_url: 'https://yoursite.com/return'
});
| 플래그 | 기본값 | 동작 |
|---|
allow_phone_number_collection | true | 체크아웃 시 전화번호 필드를 표시 |
require_phone_number | false | 전화번호 필드를 필수로 설정 |
require_phone_number: true는 allow_phone_number_collection: true가 필요합니다. API는 require_phone_number가 참인 값으로 설정된 세션을 거부합니다.
B2B SaaS, 규제 산업 또는 지원, 사기 검토 또는 컴플라이언스를 위한 검증 된 연락처 채널이 필요한 모든 흐름에 유용합니다.
자세히 알아보기: 체크아웃 기능 | 체크아웃 세션 생성 API
버그 수정 및 개선사항
- 플랫폼 전반에 걸친 사소한 버그 수정 및 안정성 개선