---
title: "구독 연동"
description: "체험 기간이 있는 경우와 없는 경우 모두에 대해 구독 생성, 활성화, 자동 갱신을 설명합니다."
source: "https://docs.tokenz.one/ko-KR/v2/subscriptions/get-started"
api_version: "v2"
locale: "ko-KR"
version_status: "current"
docs_stage: "prod"
---

# 구독 연동

체험 기간이 있는 경우와 없는 경우 모두에 대해 구독 생성, 활성화, 자동 갱신을 설명합니다.

## 사전 준비

대시보드의 API 비밀 키가 필요합니다. 일회성 결제를 아직 연동하지 않았다면 [Checkout](https://docs.tokenz.one/ko-KR/v2/checkout)을 참고하세요. 구독도 같은 Checkout Session 흐름을 사용합니다.

## 1. 구독 Checkout Session 생성

정기 계약 정보를 지정하는 `subscription` 블록을 포함하여 Checkout Session을 생성하세요. 할인되지 않은 단일 항목만 허용됩니다.

```bash
curl --request POST \
  --url https://api.tokenz.one/v2/checkoutsession \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --data '{
    "itemDetails": [{
      "product": {
        "price": { "amount": 1000, "currency": "USD" },
        "quantity": 1,
        "label": "Pro Plan (Monthly)",
        "images": ["https://example.com/pro-plan.png"],
        "taxCategory": "SAAS"
      }
    }],
    "subscription": {
      "interval": { "unit": "MONTH", "count": 1 },
      "trialPeriodDays": 7,
      "dunningMode": "RETRY"
    },
    "successUrl": "https://example.com/success",
    "pendingUrl": "https://example.com/pending",
    "cancelUrl": "https://example.com/cancel",
    "customerInfo": {
      "emailAddress": "consumer@example.com"
    }
  }'
```

### 구독 매개변수

- `interval` (필수): `unit`(`WEEK`, `MONTH`, `YEAR`)과 `count`(1 이상 정수, 갱신 간 단위 수)로 구성된 청구 주기입니다. 예를 들어 `{ "unit": "MONTH", "count": 1 }`은 매월 갱신됩니다.
- `trialPeriodDays` (선택, 1~365): 첫 청구 전 일수입니다. 체험이 없으면 생략하세요.
- `dunningMode` (선택): `RETRY`(기본) 또는 `CANCEL_IMMEDIATELY`. [수명 주기 및 청구](https://docs.tokenz.one/ko-KR/v2/subscriptions/lifecycle#dunning-(failed-payment-recovery))를 참고하세요.
- `dunningMaxAttempts` (선택, 기본 3), `dunningExpireAfterHours` (선택, 기본 24): `dunningMode`가 `RETRY`일 때만 사용합니다.

### 응답

```json
{
  "id": "checkoutsession_1p4LPTRKB5Z",
  "object": "checkoutsession",
  "url": "https://checkout.tokenz.one/1p4LPTRKB5Z",
  "test": false,
  "subscription": {
    "id": "subscription_1p4LS47fB1h",
    "object": "subscription",
    "status": "created",
    "test": false,
    "items": [
      {
        "id": "item_1p4LS47fB1i",
        "detail": {
          "product": {
            "price": { "amount": 1000, "currency": "USD" },
            "quantity": 1,
            "label": "Pro Plan (Monthly)",
            "images": ["https://example.com/pro-plan.png"]
          }
        }
      }
    ],
    "interval": { "unit": "MONTH", "count": 1 },
    "createdAt": "2026-07-01T00:00:00Z",
    "updatedAt": "2026-07-01T00:00:00Z"
  }
}
```

> **참고:** `trialPeriodDays`를 생략하면 초기 청구용 `order` 객체도 응답에 포함됩니다.

## 2. 고객을 이동시켜 설정 완료

반환된 `url`로 고객을 이동시키세요. Tokenz 호스팅 결제 페이지가 다음 절차를 처리합니다.

- 고객 지역, 통화, 적용 세금 결정
- 카드 정보 수집 및 카드사가 요구하는 3D Secure 인증
- 이후 갱신에 필요한 정기 청구에 대한 고객 동의 받기([결제 수단 및 동의](https://docs.tokenz.one/ko-KR/v2/subscriptions/payment-methods) 참고)
- **체험 없음**: 첫 주문을 즉시 청구하고 구독 활성화
- **체험 있음**: 청구 없이 체험 시작

완료 후 결과에 따라 `successUrl`, `pendingUrl`, `cancelUrl`로 이동합니다. 일회성 Checkout Session과 같은 리디렉션 규칙입니다.

## 3. 자동 활성화 및 갱신

추가 호출은 필요하지 않습니다.

- 체험이 없으면 초기 청구 성공 즉시 `active`가 됩니다.
- 체험이 있으면 종료 시 첫 주문을 자동 생성·청구하고 성공 시 활성화합니다.
- 이후 `active`인 동안 매 청구 기간 종료 시 새 주문을 자동 생성·청구합니다.

성공 시 `subscription.trial_started`, `subscription.activated`, `subscription.renewed`, 청구 실패 시 `subscription.unpaid`를 수신하여 자체 기록을 동기화하세요. [웹훅](https://docs.tokenz.one/ko-KR/v2/subscriptions/webhooks)을 참고하세요.

```mermaid
sequenceDiagram;
autonumber;
participant C as 고객;
participant M as 판매자 서버;
participant T as Tokenz API;
participant TC as Tokenz 호스팅 Checkout;
participant W as 판매자 웹훅 핸들러;
M->>T: POST /v2/checkoutsession (subscription 블록 포함);
T-->>M: checkoutSession + subscription (created);
M-->>TC: 고객을 Checkout Session url로 이동;
TC->>TC: 카드 수집, 지역·세금 결정, 동의 기록;
alt 체험 없음
TC->>TC: 초기 주문 청구, 구독 active 전환;
else 체험 기간 설정됨
TC->>TC: 구독 trialing 전환 (아직 청구 없음);
Note over T: trialEnd에 첫 주문 자동 생성·청구;
T->>T: 구독 active 전환;
end
TC-->>C: successUrl / pendingUrl / cancelUrl로 복귀;
T->>W: webhook: subscription.trial_started / subscription.activated;
loop 매 청구 기간;
T->>T: 갱신 주문 생성, 저장된 카드로 자동 청구;
T->>W: 웹훅: subscription.renewed (실패 시 subscription.unpaid);
end
```

## 구독 확인

Tokenz 대시보드에서 계정의 구독을 조회·관리할 수 있습니다. 자체 시스템에서는 폴링 대신 위 웹훅으로 각 구독의 최신 상태를 유지하세요.

## 테스트

- 테스트 API 키(`secret_test_` 접두사)로 테스트 구독을 생성하세요. 테스트 ID에는 `_t` 접미사가 있습니다(예: `subscription_1p4LS47fB1h_t`).
- 테스트 모드에서는 실제 카드 네트워크 없이 결과를 시뮬레이션할 수 있습니다. 첫 결제와 미납 복구는 **테스트 승인 결과**에서 **성공** 또는 **거절**을 선택하세요. 청구 없이 체험을 시작하거나 카드를 업데이트할 때는 **테스트 동의 결과**에서 **동의함** 또는 **거부됨**을 선택하세요.
- 테스트 구독은 대시보드에서 정규 청구 일정을 기다리지 않고 갱신 청구를 실행할 수도 있습니다.