구독 연동

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

사전 준비

대시보드의 API 비밀 키가 필요합니다. 일회성 결제를 아직 연동하지 않았다면 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. 수명 주기 및 청구를 참고하세요.
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 인증
이후 갱신에 필요한 정기 청구에 대한 고객 동의 받기(결제 수단 및 동의 참고)
체험 없음: 첫 주문을 즉시 청구하고 구독 활성화
체험 있음: 청구 없이 체험 시작

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

3. 자동 활성화 및 갱신

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

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

성공 시 subscription.trial_started, subscription.activated, subscription.renewed, 청구 실패 시 subscription.unpaid를 수신하여 자체 기록을 동기화하세요. 웹훅을 참고하세요.

다이어그램

구독 확인

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

테스트

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