구독 시스템

문서 정보

작성일: 2026-02-27
최종 업데이트: 2026-03-07
버전: v3.0.0

TL;DR

구독은 사용자의 멤버십(PLUS/PRO) 정기 결제를 관리합니다. 매일 자정 스케줄러가 결제일이 도래한 구독을 갱신하고, 결제 실패 시 최대 3회 재시도합니다. 플랜 변경(업그레이드/다운그레이드)과 환불(전체/차액)을 지원합니다.

핵심 개념

구독이란?

사용자가 멤버십을 결제하면 구독이 생성됩니다. 구독은 매달 자동으로 결제를 갱신하여 멤버십 혜택을 유지합니다.

용어	설명
구독	정기 결제 정보를 관리하는 핵심 데이터
빌링키	결제 수단(카드) 정보 토큰 — 실제 카드 번호는 저장하지 않음
결제 내역	각 결제 시도마다 생성되는 기록
멤버십 상품	구독 상품 정보 (PLUS 월간, PRO 월간 등)

구독과 관련된 데이터

구독 시스템은 세 가지 데이터가 함께 동작합니다.

데이터	역할	핵심 정보
구독 정보	결제 및 구독 상태 관리	다음 결제일, 구독 상태, 구독 가격
권한 정보	사용자 멤버십 등급 판단	유효 기간, 현재 플랜
리워드 카운터	KOK 시청 리워드 한도 추적	현재 사이클 시작/종료일, 사용 횟수

다음 결제일이 기준

구독의 다음 결제일이 기준 값입니다. 결제 성공 시 권한의 유효 기간과 리워드 카운터의 종료일이 모두 이 값으로 맞춰집니다.

플랜 구성

스포클립은 세 가지 멤버십 플랜을 제공합니다.

플랜	가격	설명
FREE	무료	기본 기능
PLUS	7,900원/월	확장 기능 + KOK 시청 리워드
PRO	9,900원/월	모든 기능 + 최대 리워드

플랜 계층: FREE < PLUS < PRO

업그레이드: 낮은 플랜 → 높은 플랜 (예: PLUS → PRO)
다운그레이드: 높은 플랜 → 낮은 플랜 (예: PRO → PLUS)

플랜별 주요 혜택

항목	FREE	PLUS	PRO
광고	있음	없음	없음
스트리밍 화질	480p	4K	4K
다운로드	불가	가능	가능
카메라 접근	제한	무제한	무제한
스케줄 앨범	불가	가능	가능
스케줄 접근	녹화 종료 3시간 후	즉시	즉시
웹 플랫폼	-	-	지원
콕 저장	불가	30회/스케줄	90회/스케줄
마이콕 보유	불가	최대 50개	최대 150개
KOK 시청 리워드	불가	가능	가능

구독 상태 전이

구독은 생성부터 만료까지 다음과 같은 상태를 거칩니다.

상태별 설명

상태	의미	혜택	비고
PENDING_PAYMENT	결제 대기	없음	첫 결제 요청 직후
ACTIVE	정상 구독	사용 가능	정기 결제 성공 상태
UNPAID	결제 실패 (재시도 중)	일시 중단	최대 3회 재시도
PENDING_CANCEL	취소 예정	사용 가능	다음 결제일까지 혜택 유지
CANCELED	취소 완료	없음	환불 또는 만료
FAILED	결제 실패 종료	없음	3회 재시도 실패 또는 첫 결제 실패

취소 예정(PENDING_CANCEL)과 취소(CANCELED)의 차이

PENDING_CANCEL 상태에서는 다음 결제일까지 멤버십 혜택을 계속 사용할 수 있습니다. 실제 취소(CANCELED)는 다음 결제일 스케줄러 실행 시 처리됩니다.

구독 생성

사용자가 멤버십을 구독하면 다음 과정이 진행됩니다.

핵심 포인트

가격: 구독 시점의 최신 상품 가격이 적용됩니다
다음 결제일: 결제 주기(월간)에 따라 자동 계산됩니다
기존 스케줄 업그레이드: 사용자가 선택하면 기존 FREE 스케줄을 상위 플랜으로 업그레이드하며, 이 경우 환불이 불가능해집니다

플랜 변경

즉시 변경 (IMMEDIATE)

업그레이드만 가능 — 즉시 상위 플랜으로 변경되며, 차액을 결제합니다.

항목	설명
방향	UP만 가능 (PLUS → PRO)
결제	당일 업그레이드는 플랜 차액 전액 결제, 다음 날부터는 남은 기간을 반영한 차액 결제
적용 시점	즉시
환불	7일 이내 차액 환불 가능 (쿨링오프)

즉시 업그레이드는 "PRO 가격을 다시 처음부터 결제"하는 방식이 아닙니다. 이미 사용 중인 PLUS 구독을 PRO로 올리는 것이므로, 업그레이드 시점에 따라 추가 결제 금액이 달라질 수 있습니다.

결제한 당일 업그레이드하면 플랜 차이만 그대로 결제합니다.
결제한 다음 날부터 업그레이드하면 이번 결제 주기에서 남아 있는 기간만 반영한 차액을 결제합니다.

예를 들어 PLUS가 7,900원, PRO가 9,900원이면:

결제 당일 업그레이드: 2,000원 추가 결제
결제 다음 날 이후 업그레이드: 2,000원보다 적은 금액이 나올 수 있음

기존 스케줄 업그레이드 주의

기존 스케줄에 상위 플랜 적용을 선택하면 환불이 불가능해집니다.

예약 변경 (RESERVED)

업그레이드/다운그레이드 모두 가능 — 다음 결제일에 플랜이 변경됩니다.

항목	설명
방향	UP, DOWN 모두 가능
결제	다음 결제일에 새 플랜 가격으로 결제
적용 시점	다음 결제일
취소	결제일 전까지 예약 취소 가능

예약 변경이 설정되면 구독 조회 시 예약 변경 정보가 포함됩니다.

정기 결제 갱신

갱신 스케줄러

매일 자정(KST) 스케줄러가 실행되어 결제일이 도래한 구독을 자동 갱신합니다.

갱신 대상 조건

스케줄러는 다음 조건을 모두 만족하는 구독을 대상으로 합니다.

조건	설명
다음 결제일이 오늘 이전	결제일이 도래했거나 지난 구독
구독 상태가 ACTIVE, PENDING_CANCEL, UNPAID 중 하나	갱신 또는 만료 처리 가능한 상태
재시도 횟수 3회 미만	아직 재시도 가능
결제 수단이 활성 상태	유효한 카드 등록

갱신 시 가격

항목	설명
기본 가격	구독 시점 가격 (예: PLUS 7,900원)
리워드 차감	사용자 설정에 따라 리워드 잔액 자동 차감
최종 결제액	기본 가격 - 리워드 차감액 (최소 0원)

예약 변경이 있는 경우

다음 결제일에 예약된 플랜 변경이 있으면, 새 플랜으로 변경 후 새 가격으로 결제됩니다.

배치 처리

한 번에 50개씩 처리하며, 최대 10 사이클까지 실행됩니다. 남은 건은 다음 스케줄러 실행에서 처리됩니다.

결제 실패와 재시도

정기 결제가 실패하면 자동으로 재시도 프로세스가 시작됩니다.

재시도 흐름

재시도 규칙

횟수	시점	실패 시
1차	결제 실패 후 24시간	UNPAID 유지
2차	최초 실패 후 3일차	UNPAID 유지
3차	최초 실패 후 5일차	FAILED (구독 종료)

첫 결제 실패

첫 결제(구독 생성 시 결제)가 실패하면 재시도 없이 즉시 FAILED 상태로 변경됩니다. 사용자가 직접 다시 구독해야 합니다.

구독 취소와 환불

구독 취소

사용자가 구독 취소를 요청하면 즉시 해지되지 않고, 다음 결제일까지 혜택이 유지됩니다.

해지 철회: PENDING_CANCEL 상태에서 철회하면 ACTIVE로 복원됩니다

환불

환불은 취소와 다르게 즉시 구독이 종료되고 결제 금액이 반환됩니다. 두 가지 환불 유형이 있습니다.

구독 전체 환불 (REFUND_SUBSCRIPTION)

구독 결제 전액을 환불받고 구독이 즉시 종료됩니다.

조건	설명
가입 후 7일 이내	마지막 정기 결제일 기준
멤버십 혜택 미사용	환불 가능 상태
업그레이드 상태인 경우	이전 구독도 환불 가능 상태여야 함

플랜 변경 차액 환불 (REFUND_CHANGE)

업그레이드 시 결제한 차액만 환불받고, 이전 플랜으로 복원됩니다.

조건	설명
업그레이드 후 7일 이내	쿨링오프 기간
업그레이드 이력 존재	이전 플랜 정보가 남아있어야 함

차액 환불 시 예약된 플랜 변경도 함께 취소됩니다.

환불 불가 사유

환불 가능 여부가 불가로 변경되는 경우:

시점	사유
업그레이드 시 기존 스케줄에 적용	기존 스케줄에 상위 플랜 적용을 선택
구독 후 멤버십 스케줄 생성	녹화 생성 시 자동
스케줄 예약	예약 시 자동
유료 스케줄 공유 수신	공유받은 시점에 자동

PENDING_CANCEL 상태에서도 환불 가능

취소 예정(PENDING_CANCEL) 상태에서도 환불 조건을 충족하면 환불이 가능합니다. 이 경우 다음 결제일을 기다리지 않고 즉시 환불+해지됩니다.

환불 후 무료 체험 복원

환불 시 유효한 무료 체험 기간이 남아있으면 자동으로 무료 체험 상태로 복원됩니다. 남아있지 않으면 권한이 비활성화됩니다.

리워드 자동 적용

사용자 설정(membership_auto_apply_reward)에 따라 멤버십 결제 시 리워드(포인트)를 자동으로 차감하여 결제 금액을 줄일 수 있습니다.

적용 대상

결제 유형	적용 시점	포인트 카테고리
첫 구독 (SUBSCRIPTION)	구독 요청 시	MEMBERSHIP_SUBSCRIBE
업그레이드 (UPGRADE)	플랜 변경 요청 시	MEMBERSHIP_UPGRADE
갱신 (RENEWAL)	결제 갱신 시	MEMBERSHIP_RENEWAL

자동 차감 조건

항목	설명
사용자 설정	리워드 자동 차감 ON
차감 대상	모든 리워드 (콕 시청, 광고 시청, 출석체크, 주간 보너스, 공유 콕 시청, 콕 공유 수수료, 환불 복원 포함)
차감 한도	결제 가격 이하 (리워드 잔액과 결제 가격 중 작은 값)
차감 방식	먼저 적립된 리워드부터 차감 (FIFO)

0원 결제

리워드 차감으로 결제 금액이 0원이 되면 PG사 호출 없이 내부에서 결제 완료 처리합니다.

환불 시 리워드 복원

환불된 결제에 자동 적용되었던 리워드 포인트는 MEMBERSHIP_REFUND 카테고리로 재적립됩니다. 복원된 리워드의 유효기간은 복원일로부터 12개월입니다.

환불 유형	결제 금액	PG 환불	리워드 복원
구독 전체 환불 (유료)	> 0원	PG 환불	웹훅에서 복원
구독 전체 환불 (0원)	= 0원	스킵	환불 시 직접 복원
차액 환불 (유료)	> 0원	PG 환불	환불 시 직접 복원
차액 환불 (0원)	= 0원	스킵	환불 시 직접 복원

상세 플로우는 시나리오 7: 리워드 자동 적용을 참조하세요.

라이프사이클 레퍼런스

구독 시스템의 세 가지 데이터(구독, 권한, 리워드 카운터)가 각 이벤트에서 어떻게 변하는지 정리합니다.

데이터 관계

동기화 규칙

구독의 다음 결제일이 기준 값입니다. 결제 성공 시 나머지 데이터가 이 값에 맞춰집니다.

데이터	동기화 대상	규칙
구독	다음 결제일	기준 값 — 결제 시점에 계산
권한	유효 기간	= 구독의 다음 결제일
리워드 카운터	사이클 종료일	= 구독의 다음 결제일

이벤트별 데이터 변화

이벤트	구독	권한	리워드 카운터
구독 생성	생성 → ACTIVE, 결제일 설정	FREE → PLUS/PRO, ACTIVE	미생성
정기 결제 갱신	결제일 갱신, 재시도 초기화	유효 기간 갱신	사이클 리셋
즉시 플랜 변경	플랜/가격 변경, 이전 플랜 저장	플랜 업그레이드	변경 없음
예약 플랜 변경	예약 정보 저장	변경 없음	변경 없음
구독 취소	ACTIVE → PENDING_CANCEL	변경 없음 (혜택 유지)	변경 없음
해지 철회	PENDING_CANCEL → ACTIVE	변경 없음	변경 없음
차액 환불	이전 플랜 복원, 업그레이드 초기화	플랜 다운그레이드	변경 없음
전체 환불	→ CANCELED	→ FREE (Trial 복원 가능)	삭제
KOK 시청 리워드	변경 없음	변경 없음	사용 횟수 +1
구독 만료	→ CANCELED	→ FREE, INACTIVE	유지

권한 상태 다이어그램

변경 이력

버전	날짜	변경 내용
v3.2.0	2026-04-01	즉시 업그레이드 차액 정책 반영 - 당일 업그레이드 전액 차액 정책 반영 - 다음 날부터 남은 기간 기준 차액 정책 명시 - 차액 환불 예시를 실제 결제 금액 기준으로 정리
v3.1.0	2026-03-12	리워드 자동 적용 확장 - 리워드 자동 차감 → 자동 적용으로 명칭 변경 - 첫 구독/업그레이드 시 리워드 자동 적용 추가 - 환불 시 리워드 복원 (MEMBERSHIP_REFUND) 섹션 추가
v3.0.0	2026-03-07	구독 + 라이프사이클 통합 - 멤버십 라이프사이클 문서 통합 (동기화 규칙, 이벤트별 데이터 변화, 권한 상태도) - 플랜별 주요 혜택 테이블 추가 (콕/마이콕 한도 포함) - FAQ 섹션 → 멤버십 FAQ 문서로 분리
v2.0.0	2026-03-07	전폭 개선 - PRO 플랜 추가, 플랜 계층 구조 소개 - 플랜 변경(즉시/예약) 섹션 신규 추가 - 차액 환불(REFUND_CHANGE) 추가 - PENDING_CANCEL 환불 가능 명시 - 전체 팀원 대상 접근성 개선 (개발자 용어 → 일반 용어) - 데이터 모델 섹션 제거 (개발자 전용 → 코드 참조) - 업그레이드 상태 전체 환불 순서 설명 추가
v1.0.0	2026-02-27	초기 문서 작성 - 구독 상태 전이 다이어그램 - 결제 재시도 로직 - 구독 취소/환불 정책 - 리워드 자동 차감

문서 정보​

목차​

핵심 개념​

구독이란?​

구독과 관련된 데이터​

플랜 구성​

플랜별 주요 혜택​

구독 상태 전이​

상태별 설명​

구독 생성​

핵심 포인트​

플랜 변경​

즉시 변경 (IMMEDIATE)​

예약 변경 (RESERVED)​

정기 결제 갱신​

갱신 스케줄러​

갱신 대상 조건​

갱신 시 가격​

예약 변경이 있는 경우​

결제 실패와 재시도​

재시도 흐름​

재시도 규칙​

구독 취소와 환불​

구독 취소​

환불​

구독 전체 환불 (REFUND_SUBSCRIPTION)​

플랜 변경 차액 환불 (REFUND_CHANGE)​

환불 불가 사유​

환불 후 무료 체험 복원​

리워드 자동 적용​

적용 대상​

자동 차감 조건​

0원 결제​

환불 시 리워드 복원​

라이프사이클 레퍼런스​

데이터 관계​

동기화 규칙​

이벤트별 데이터 변화​

권한 상태 다이어그램​

관련 문서​

변경 이력​