구독 | Tokenz Docs

Tokenz Subscriptions API로 구독 결제 생성부터 청구, 미납 결제 재시도, 요금제 변경, 취소까지 정기 결제 상품을 판매하는 방법을 알아봅니다.

구독은 활성 상태인 동안 일정 주기(주·월·년)마다 새 주문을 자동 생성하고 저장된 결제 수단으로 청구합니다. Tokenz가 갱신 청구 예약, 결제 실패 재시도, 갱신 알림, 각 단계의 백엔드 웹훅 알림까지 전체 청구 수명 주기를 관리합니다.

금액 형식: 금액 값(amount 필드 등)은 각 통화의 최소 단위로 표시합니다. 통화별 정확한 형식은 지원 통화를 참고하세요.

참고: 구독은 현재 Merchant of Record(MoR) 모델의 판매자에게만 제공됩니다.

개요

Subscriptions API는 일회성 주문과 같은 Checkout Session을 기반으로 합니다.

생성: subscription 블록을 포함한 Checkout Session으로 시작합니다. 할인되지 않은 항목을 정확히 하나만 허용합니다.
카드 등록 및 정기 청구 동의: 고객이 Checkout에서 카드 등록과 판매자 주도 거래(MIT) 동의를 완료합니다. 체험 기간이 없으면 첫 결제도 완료합니다. 이후 갱신은 고객의 추가 조작 없이 청구됩니다.
자동 청구: active인 동안 청구 기간이 끝날 때마다 새 주문을 생성하고 저장된 카드로 청구합니다.
관리: 고객은 Tokenz 호스팅 화면에서 결제 수단을 업데이트하고, 판매자는 고객의 요금제를 변경하거나 구독을 취소할 수 있습니다.
후속 처리: 체험 시작, 활성화, 갱신, 미납, 결제 수단 업데이트, 요금제 변경, 취소, 만료 등 모든 상태 전환을 웹훅으로 받습니다.

구독: 정기 결제 기록입니다. 가격, 청구 주기, 체험 설정, 미납 재시도 전략, 현재 청구 기간, 고객 결제 수단을 포함합니다.
청구 주기: unit(WEEK, MONTH, YEAR)과 count(갱신 간 단위 수)로 지정합니다. 월·년 단위 갱신은 첫 결제와 같은 일자에 이루어지며, 해당 일자가 없는 달에는 말일을 사용합니다.
체험 기간: 첫 청구 전 선택적 기간(1~365일)입니다. 설정하면 초기 주문 없이 구독이 생성되고 체험 종료 시 첫 주문이 자동 생성됩니다.
결제 수단 동의: 구독은 카드 결제 수단만 지원합니다. 초기 결제 승인 또는 전용 동의 절차로 매번 3D Secure 인증 없이 갱신 청구할 수 있는 권한을 받습니다.
미납 결제 재시도: 갱신 청구 실패 후 구독 만료 전까지 적용하는 재시도 전략입니다.
요금제 변경: 아이템 또는 청구 주기 변경 요청입니다. 일할 계산하여 즉시 적용하거나 다음 청구 기간으로 미룰 수 있습니다.