구독 시스템

문서 정보

작성일: 2026-02-27
최종 업데이트: 2026-05-06
버전: v3.6.0

TL;DR

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

핵심 개념

구독이란?

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

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

구독과 관련된 데이터

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

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

다음 결제일이 기준

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

플랜 구성

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

플랜	가격 (웹/Portone)	가격 (Apple / Google IAP)	설명
FREE	무료	무료	기본 기능
PLUS	7,900원/월	9,500원/월	확장 기능 + KOK 시청 리워드
PRO	9,900원/월	11,900원/월	모든 기능 + 최대 리워드

인앱결제(Apple/Google) 가격은 스토어 수수료 ~15% 반영하여 웹 대비 약 +20% 마크업 적용. 상세는 IAP 시스템 개요를 참고하세요. 이하 시나리오 예시(업그레이드/환불 차액 계산 등)는 모두 웹 가격 기준입니다.

플랜 계층: 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원보다 적은 금액이 나올 수 있음

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

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

IAP 구독 즉시 업그레이드 미지원

즉시 업그레이드는 웹/PortOne 구독에서만 지원합니다. IAP 구독은 Apple/Google이 결제와 proration을 관리하므로, 서버가 남은 일수를 계산해 차액을 청구하는 현재 정책과 맞지 않습니다. 따라서 IAP 구독에서는 CHANGE_PLAN_IMMEDIATE 액션을 노출하지 않고, 서버도 IMMEDIATE 플랜 변경 요청을 차단합니다.

예약 변경 (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 상태로 변경됩니다. 사용자가 직접 다시 구독해야 합니다.

조회 API와 사용자 유도

현재 구독 조회 API는 사용자가 조치해야 하는 중간 상태도 반환합니다. 프론트엔드는 새 구독 시도를 다시 열기보다 상태별 안내와 적절한 CTA를 제공해야 합니다.

상태	API 노출	사용자 안내	권장 CTA
`ACTIVE`	예	정상 구독 중	플랜 변경, 해지 관리
`PENDING_CANCEL`	예	해지 예정이지만 혜택 유지 중	해지 철회
`PENDING_PAYMENT`	예	결제 확인 중	구독 상태 새로고침
`UNPAID`	예	정기 결제 실패 후 재시도 또는 조치 필요	결제 수단 확인 안내
`FAILED`	아니오	종료 상태	새 구독 가능
`CANCELED`	아니오	종료 상태	새 구독 가능

API	상태 필드	포함 상태
`GET /pass-memberships`	`subscriptionStatus`	`ACTIVE`, `PENDING_CANCEL`, `PENDING_PAYMENT`, `UNPAID`
`GET /pass-memberships/management`	`subscription.status`	`ACTIVE`, `PENDING_CANCEL`, `PENDING_PAYMENT`, `UNPAID`

서버도 동일한 기준으로 신규 웹 구독 생성을 방어합니다. 위 네 상태 중 하나가 존재하면 새 구독 생성은 차단하고 기존 구독 상태를 조회하도록 유도합니다.

정기 결제 실패 운영 알림

정기 결제 실패는 Discord 결제 알림 채널로 전송합니다. 알림은 운영자가 조치해야 하는 실패와, 결제 제공자가 재시도 중인 실패를 구분할 수 있도록 전송합니다.

PortOne 웹 결제와 RevenueCat IAP 구독은 실패와 재시도 주체가 다릅니다. PortOne은 서버가 결제 요청을 만들고 실패 웹훅에서 retryCount를 올립니다. RevenueCat IAP는 Apple/Google/RevenueCat이 재시도를 관리하고, 서버는 BILLING_ISSUE와 EXPIRATION 웹훅을 받아 운영 알림과 상태 동기화를 수행합니다.

알림 경로

PortOne 실패 유형별 처리

실패 유형	발생 시점	구독 상태 변경	결제 내역 상태	Discord 알림
결제 요청 실패	서버가 PortOne 빌링키 결제 API를 호출하는 단계	변경 없음	FAILED	멤버십 정기 결제 요청 실패
정기 결제 실패 웹훅	PortOne이 결제 실패 웹훅을 보낸 단계	retryCount 3회 미만: UNPAID	FAILED	멤버십 정기 결제 실패
정기 결제 최종 실패 웹훅	retryCount가 최대 재시도 횟수에 도달한 단계	FAILED	FAILED	멤버십 정기 결제 최종 실패

결제 요청 실패와 실패 웹훅의 차이

결제 요청 실패는 서버가 PortOne에 결제 요청을 정상 접수시키지 못한 경우입니다. 이때는 PortOne 실패 웹훅이 오지 않을 수 있으므로 별도 알림을 보냅니다.

실패 웹훅은 PortOne이 결제 요청을 접수한 뒤 실제 카드 결제에 실패한 경우입니다. 이때는 웹훅에서 retryCount를 증가시키고, 최대 3회까지 재시도 상태를 유지합니다.

RevenueCat IAP 실패 유형별 처리

이벤트	의미	구독 상태 변경	Discord 알림
`BILLING_ISSUE`	Apple/Google 구독 갱신 청구 문제 발생	변경 없음	IAP 멤버십 청구 문제
`EXPIRATION`	RevenueCat 구독 최종 만료	CANCELED	IAP 멤버십 구독 만료
`RENEWAL`	IAP 구독 정상 갱신	ACTIVE	전송하지 않음

IAP 청구 문제는 즉시 종료하지 않음

BILLING_ISSUE는 스토어와 RevenueCat이 재시도 중임을 의미합니다. 이 이벤트만으로 서버 구독을 FAILED 또는 CANCELED로 바꾸지 않습니다. 최종 종료 처리는 RevenueCat EXPIRATION 이벤트에서 수행합니다.

재시도와 중복 웹훅

PortOne은 같은 거래에 대해 여러 번 웹훅을 재전송할 수 있습니다. 서버는 transactionId와 이벤트 타입으로 만든 멱등성 키를 기준으로 이미 처리한 웹훅을 다시 처리하지 않습니다.

항목	기준
멱등성 키	`${transactionId}-${eventType}`
중복 웹훅	기존 웹훅 로그가 있으면 성공 응답 후 종료
재시도 판단	중복 웹훅이 아니라 실제 실패 이벤트가 처리될 때만 `retryCount` 증가

알림 메시지 필드

필드	설명
상태	웹훅 처리 후 구독 상태
재시도	현재 retryCount / 최대 retryCount
금액	결제 시도 금액
userId	대상 사용자 ID
subscriptionId	대상 구독 ID
paymentUuid	서버 결제 내역 UUID
portonePaymentId	PortOne 결제 ID
error	결제 요청 실패 시 예외 메시지

운영 설정

항목	값
Discord Webhook env	`DISCORD_PAYMENT_ALERT_WEBHOOK_URL`
알림 서비스	`PassMembershipPaymentAlertService`
배치 결제 요청 실패 감지	`RenewSubscriptionCommand`
PortOne 실패 웹훅 감지	`PassMembershipWebhookService`
RevenueCat 청구 문제 감지	`ProcessIapSubscriptionBillingIssueCommand`
RevenueCat 만료 감지	`ProcessIapSubscriptionExpirationCommand`

알림 실패 처리

Discord 알림 전송 실패는 결제 배치나 웹훅 처리를 실패시키지 않습니다. 알림 전송 실패는 서버 로그에 남기고 원래 결제 처리 흐름을 계속 진행합니다.

구독 취소와 환불

구독 취소

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

해지 철회: 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.6.0	2026-05-06	IAP 즉시 업그레이드 차단 정책 추가 - IAP 구독에서는 `CHANGE_PLAN_IMMEDIATE`를 노출하지 않는 정책 명시 - 웹/PortOne 구독만 남은 일수 기준 즉시 업그레이드를 지원하는 이유 설명
v3.5.0	2026-05-06	중간 구독 상태 조회 정책 추가 - `PENDING_PAYMENT`, `UNPAID` 상태의 사용자 안내와 조회 API 노출 기준 명시 - 신규 웹 구독 생성 방어 기준과 조회 상태 기준 일치
v3.4.0	2026-05-06	RevenueCat IAP 결제 실패 알림 문서화 - `BILLING_ISSUE`와 `EXPIRATION` 알림 기준 추가 - IAP 청구 문제는 즉시 종료하지 않는 정책 명시
v3.3.0	2026-05-06	정기 결제 실패 운영 알림 문서화 - PortOne 결제 요청 실패와 실패 웹훅 처리 경로 구분 - Discord 결제 알림 메시지와 운영 설정 추가 - 중복 웹훅 멱등성 기준 명시
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)​

정기 결제 갱신​

갱신 스케줄러​

갱신 대상 조건​

갱신 시 가격​

예약 변경이 있는 경우​

결제 실패와 재시도​

재시도 흐름​

재시도 규칙​

조회 API와 사용자 유도​

정기 결제 실패 운영 알림​

알림 경로​

PortOne 실패 유형별 처리​

RevenueCat IAP 실패 유형별 처리​

재시도와 중복 웹훅​

알림 메시지 필드​

운영 설정​

구독 취소와 환불​

구독 취소​

환불​

구독 전체 환불 (REFUND_SUBSCRIPTION)​

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

환불 불가 사유​

환불 후 무료 체험 복원​

리워드 자동 적용​

적용 대상​

자동 차감 조건​

0원 결제​

환불 시 리워드 복원​

라이프사이클 레퍼런스​

데이터 관계​

동기화 규칙​

이벤트별 데이터 변화​

권한 상태 다이어그램​

관련 문서​

변경 이력​