---
title: "구독"
description: "Tokenz Subscriptions API로 구독 결제 생성부터 청구, 미납 결제 재시도, 요금제 변경, 취소까지 정기 결제 상품을 판매하는 방법을 알아봅니다."
source: "https://docs.tokenz.one/ko-KR/v2/subscriptions"
api_version: "v2"
locale: "ko-KR"
version_status: "current"
docs_stage: "prod"
---

# 구독

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

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

**금액 형식:** 금액 값(`amount` 필드 등)은 각 통화의 최소 단위로 표시합니다. 통화별 정확한 형식은 [지원 통화](https://docs.tokenz.one/ko-KR/v2/checkout/currency)를 참고하세요.

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

## 개요

Subscriptions API는 일회성 주문과 같은 [Checkout Session](https://docs.tokenz.one/ko-KR/v2/checkout)을 기반으로 합니다.

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

## 핵심 개념

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

## 가이드 구성

- [수명 주기 및 청구](https://docs.tokenz.one/ko-KR/v2/subscriptions/lifecycle) — 상태, 청구 기간, 체험, 미납 재시도, 취소, 갱신 알림
- [구독 연동](https://docs.tokenz.one/ko-KR/v2/subscriptions/get-started) — 구독 결제 생성, 활성화, 갱신
- [결제 수단 및 동의](https://docs.tokenz.one/ko-KR/v2/subscriptions/payment-methods) — MIT 동의와 고객 카드 업데이트
- [웹훅](https://docs.tokenz.one/ko-KR/v2/subscriptions/webhooks) — 전체 이벤트 목록과 페이로드 예제