v1.101.0 (2026년 6월 2일) - Dodo Payments Documentation

새로운 기능

1. 구독 결제 재시도

실패한 구독 갱신 결제는 이제 자동으로 재시도되어 수익을 복구할 수 있으며, 통합 작업이 필요하지 않습니다. 설정 → 복구에서 활성화하고 복구 창을 설정하면 Dodo Payments는 스마트 일정에 따라 갱신을 재시도하여 성공하거나 창이 닫힐 때까지 진행합니다.

설정	설명	기본값
결제 재시도 활성화	실패한 구독 갱신 결제를 자동으로 재시도하여 수익을 복구합니다.	꺼짐 (선택적)
복구 창(일)	포기하기 전 실패한 결제를 재시도할 기간 (1–30일).	13

작동 방식

구독 갱신 결제가 실패하고 구독이 on_hold로 이동합니다.
거절이 재시도 가능한 경우(자금 부족 또는 일시적 네트워크 오류와 같은 소프트 거절), 다음 시도가 자동으로 예약됩니다.
재시도는 복구 창에 따라 세션 외에서 백오프 일정으로 발사됩니다.
첫 번째 재시도가 성공하면 구독은 active로 돌아가며 다음 청구 날짜가 정상적으로 진행됩니다.

재시도 일정 재시도는 실패한 인보이스가 생성된 시간에 고정되어 점진적으로 백오프하며, 복구 창 안에 있는 한 최대 8번의 시도를 합니다:

시도	이전 시도 후 지연
1	12시간
2	24시간
3	48시간
4	72시간
5	96시간
6	120시간
7	7일
8	7일

소프트 거절만 재시도됩니다(예: 자금 부족, 일반적 거절, 처리 또는 네트워크 오류). 하드 거절은 재시도가 결과를 바꾸지 않으므로 즉시 종료됩니다.

이는 기존의 복구 도구를 보완합니다. 구독 던닝은 고객에게 결제 수단 업데이트를 위한 이메일을 보내고, 결제 재시도는 기존 결제를 조용히 재시도합니다. 이들은 잘 연동됩니다. 자세히 알아보기: 구독 결제 재시도 | 구독 던닝

2. 비즈니스 재정산 설정

이제 기본 업그레이드 및 다운그레이드 동작을 비즈니스 레벨에서 한 번 설정하여 모든 플랜 변경 시 재정산 매개변수를 전달할 필요 없이 설정할 수 있습니다. 이러한 기본값은 고객이 고객 포털에서 플랜을 변경할 때 적용되며, 제품 컬렉션별로 이를 재정의할 수 있습니다.

업그레이드 및 다운그레이드 기본 동작을 설정하는 대시보드의 설정으로 업그레이드, 다운그레이드 및 결제 실패에 대한 개별 제어가 있음

업그레이드와 다운그레이드 방향 각각에는 두 개의 독립적인 제어가 있으며, 결제 실패 정책이 공유됩니다:

설정	필드	기본값 (업그레이드)	기본값 (다운그레이드)
새 플랜 시작 시점	`effective_at_on_upgrade` / `effective_at_on_downgrade`	`immediately`	`next_billing_date`
고객이 청구되는 방법	`proration_billing_mode_on_upgrade` / `proration_billing_mode_on_downgrade`	`difference_immediately`	`difference_immediately`
고객의 결제가 실패한 경우	`on_payment_failure`	`apply_change`	`apply_change`

새 플랜 시작 시점 (effective_at)

값	동작
`immediately`	고객이 즉시 새 플랜으로 이동합니다.
`next_billing_date`	고객이 다음 청구 날짜까지 현재 플랜에 머물다가 새 플랜으로 전환됩니다.

고객이 청구되는 방법 (proration_billing_mode)

값	동작
`prorated_immediately`	현재 청구 주기의 남은 시간을 기준으로 지금 비례 청구합니다.
`full_immediately`	지금 새 플랜의 전체 가격을 청구합니다.
`difference_immediately`	새 플랜과 현재 플랜 사이의 가격 차이만 청구합니다.
`do_not_bill`	지금은 아무 것도 청구하지 마세요. 조정은 다음 인보이스에 적용됩니다.

고객의 결제가 실패할 경우 (on_payment_failure)

값	동작
`prevent_change`	결제가 처리되지 않으면 고객을 현재 플랜에 유지합니다.
`apply_change`	결제가 처리되지 않더라도 고객을 새 플랜으로 이동합니다. 나중에 금액을 수집할 수 있습니다.

컬렉션별 재정의 모든 제품 컬렉션은 이러한 기본값을 재정의할 수 있습니다. 각 필드는 독립적이며 비즈니스 기본값을 상속하여 비즈니스 기본값을 따르거나, 해당 컬렉션에 대해서만 명시적인 값을 설정하여 재정의할 수 있습니다.

상품 컬렉션에서 '비즈니스에서 상속'으로 기본 설정된 업그레이드 및 다운그레이드 동작 재정의 섹션

각 설정은 다음 순서로 해결됩니다:

per-request value (Change Plan API) → collection field (if set) → business field → system default

플랜 변경 API에 전달되는 요청별 값(proration_billing_mode, effective_at, on_payment_failure)은 항상 컬렉션과 비즈니스 기본값보다 우선합니다. 새로운 설정은 명시적인 값이 제공되지 않는 경우에만 영향을 미칩니다. 이는 모든 고객 포털 플랜에 대한 변경 사항에 해당합니다.

자세히 알아보기: 구독 업그레이드 및 다운그레이드 | 제품 컬렉션

3. B2B 청구서를 위한 비즈니스 이름 수집

B2B 고객은 이제 구매자의 개인 이름 대신 법적 비즈니스 이름이 청구서에 표시될 수 있습니다. 결제 시 유효한 세금 ID가 제공되면 청구서에 구매 주체가 반영되도록 관련 customer_business_name을 수집할 수 있습니다.

'비즈니스로 구매' 토글이 활성화된 체크아웃 페이지로, 비즈니스 이름 및 세금 ID 번호 필드가 표시됨

고객이 체크아웃에서 비즈니스로 구매를 선택하면 비즈니스 이름과 세금 ID 번호를 입력하라는 메시지가 표시됩니다. 비즈니스 이름은 세 가지 조건이 모두 충족되었을 때만 인보이스에 나타납니다:

거래는 B2B입니다 (b2b = true)
tax_id가 존재함
비어 있지 않은 customer_business_name이 제공됨

그렇지 않으면 고객의 개인 이름이 사용됩니다. 체크아웃 시 수집 customer_business_name을 직접 설정하거나, 고객이 세금 ID와 함께 체크아웃 페이지에서 입력하거나 편집할 수 있도록 allow_customer_editing_business_name를 활성화합니다:

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_abc', quantity: 1 }],
  customer: { email: 'buyer@acme.com' },
  tax_id: 'GB123456789',
  customer_business_name: 'Acme Corp Ltd',
  feature_flags: {
    allow_tax_id: true,
    allow_customer_editing_business_name: true // let the customer enter/edit it
  },
  return_url: 'https://yoursite.com/return'
});

적용되는 위치

표면	필드	참고
체크아웃 세션	`customer_business_name`, `feature_flags.allow_customer_editing_business_name`	최대 250자; 플래그 기본값은 `false`
결제	`customer_business_name`	최대 250자
구독	`customer_business_name`	`PATCH /subscriptions/{id}`을 통해 설정하거나 해제 가능

customer_business_name은 tax_id 없이 설정할 수 없습니다. 세금 ID 없이 비즈니스 이름을 전송하면 거부됩니다. tax_id을 지우면 비즈니스 이름도 삭제됩니다. 인보이스에 두 가지가 연결되어 있기 때문입니다.

주변 공백은 잘리고, 공백만 있는 값은 명시적으로 삭제된 것으로 처리됩니다. 따라서 저장된 데이터는 인보이스에 렌더링된 내용과 항상 일치합니다.

자세히 알아보기: B2B 결제 | 청구서 관리 | 체크아웃 세션

버그 수정 및 개선 사항

플랫폼 전반에서 사소한 버그 수정 및 안정성 개선.

​새로운 기능

​1. 구독 결제 재시도

​2. 비즈니스 재정산 설정

​3. B2B 청구서를 위한 비즈니스 이름 수집

​버그 수정 및 개선 사항

새로운 기능

1. 구독 결제 재시도

2. 비즈니스 재정산 설정

3. B2B 청구서를 위한 비즈니스 이름 수집

버그 수정 및 개선 사항