구독 수명 주기 및 청구
구독 상태 전환, 청구 기간 및 갱신 계산, 결제 실패 처리 방식을 설명합니다.
상태
| 상태 | 의미 |
|---|---|
created | 구독이 생성되었지만 고객이 아직 결제 수단 등록과 정기 청구 동의를 완료하지 않았습니다. |
trialing | 체험 기간 중이며 아직 요금이 청구되지 않았습니다. |
active | 정상 청구 중입니다. 매 청구 기간 종료 시 새 주문이 자동 생성·청구됩니다. |
unpaid | 현재 기간 주문 결제에 실패했습니다. 재시도 중이며 active로 복구되거나 expired로 종료됩니다. |
canceled | 판매자 또는 고객이 취소했습니다. 최종 상태이며 더 이상 청구되지 않습니다. |
expired | 초기 결제 실패 또는 재시도 소진으로 대금을 받지 못해 종료되었습니다. 최종 상태이며 더 이상 청구되지 않습니다. |
canceled와 expired는 모두 최종 상태지만 의미가 다릅니다. 전자는 판매자나 고객의 의도적 취소, 후자는 결제 실패입니다. 자체 이탈 분석에서도 구분하세요.
청구 기간
모든 활성 구독에는 currentBillingPeriodEnd가 있고, 체험 구독에는 trialEnd도 있습니다.
- 주기:
unit(WEEK,MONTH,YEAR)과count(갱신 간 단위 수) 객체입니다. 월·년 단위 청구 기간은 청구 기준일(첫 결제 성공일)과 같은 일자를 기준으로 갱신됩니다. 대상 월에 해당 일자가 없으면 말일을 사용합니다(예: 31일 기준이면 짧은 달에는 30일 또는 28·29일). - 갱신: 현재 청구 기간 종료 시 Tokenz가 관리합니다.
체험 기간
생성 시 trialPeriodDays(1~365)를 지정하면 Checkout에서 초기 주문을 생성하지 않습니다. 대신 다음과 같이 진행됩니다.
- 고객이 카드를 제공하여 체험을 시작하고 Tokenz가 결제 네트워크에 동의를 등록합니다. 결제 수단 및 동의를 참고하세요.
trialing으로 전환되고subscription.trial_started웹훅이 전송됩니다.trialEnd에 도달하면 주문을 생성하고 저장된 카드로 청구합니다. 성공하면active로 전환되고subscription.activated가 전송됩니다.
체험이 없으면 Checkout 시 초기 주문을 생성·청구하며 결제 승인 성공 즉시 active가 됩니다.
미납 결제 재시도 및 복구
각 구독은 예약 청구 실패 시 동작을 결정하는 전략을 가집니다.
RETRY(기본): 미납 주문을dunningMaxAttempts회(기본 3)까지 재시도하며, 주문 만료 기간(dunningExpireAfterHours, 기본 24시간)까지 간격을 두고 진행합니다. 고객에게 카드 업데이트가 가능한 복구 결제 링크도 이메일로 보냅니다. 재시도 성공 시active로 돌아가고, 모두 실패하거나 주문이 만료되면expired가 됩니다.CANCEL_IMMEDIATELY: 첫 청구 실패 즉시 구독이 만료되며 재시도 기간이 없습니다.
| 필드 | 설명 |
|---|---|
dunningMode | RETRY 또는 CANCEL_IMMEDIATELY. 기본은 RETRY입니다. |
dunningMaxAttempts | RETRY일 때 최대 재시도 횟수. 1~10, 기본 3. |
dunningExpireAfterHours | RETRY일 때 미납 주문 만료까지의 시간. 1~168, 기본 24. |
참고:
unpaid에서active로 복구되어도 원래 청구 기간은 바뀌지 않습니다. 다음 갱신은 복구일이 아닌 원래 기준일에 따라 예약됩니다.
이용 권한
고객이 결제한 대상을 제공하는 방법은 구독 유형에 따라 다릅니다.
기간제 구독(예: 프리미엄 요금제)은 Subscription 객체에 이용 권한 정보가 있습니다. 구독 웹훅과 Subscription API에서 provideAccess와 provideAccessUntil을 읽으세요. provideAccess는 고객에게 이용 권한을 부여해야 하는지를 나타냅니다. provideAccessUntil은 이용 권한이 끝나는 시각이며, 기한 없이 부여되거나 권한이 부여되지 않으면 포함되지 않습니다. 이 필드에 따라 처리하세요. unpaid로 전환되었거나, 구독이 아직 active 또는 trialing인 상태에서 currentBillingPeriodEnd가 지났다는 사실만으로 권한을 회수할 이유가 되지는 않습니다.
아이템형 구독(예: 매월 재화 구매)은 Tokenz가 구독에 대해 생성하는 주문을 기준으로 아이템을 지급하세요. 이 주문의 주문 웹훅을 처리하세요. order.succeeded 등 일회성 구매와 같은 이벤트를 사용합니다. 이 주문에는 모두 subscriptionId가 포함됩니다.
취소
구독은 trialing, active, unpaid 상태에서 판매자(Tokenz 대시보드 또는 API로 직접) 또는 고객(호스팅 확인 화면)이 취소할 수 있습니다. 취소 시 다음이 적용됩니다.
canceledAt을 설정하고 이후 갱신 주문 생성을 중단합니다.- 결제 대기 주문 등 진행 중인 구독 주문을 취소합니다.
subscription.canceled웹훅을 전송합니다.
취소는 최종적이며 현재 재개할 방법이 없습니다. 다시 사용하려면 새 구독을 시작해야 합니다.
갱신 알림
일부 지역은 체험의 유료 전환이나 연간 갱신 등 특정 청구 전 사전 고지를 요구합니다. 필요한 경우 Tokenz가 자동 전송합니다.