이 기능이 왜 필요한지·무엇을 먼저 정할지는 블로그에서 다뤄요.
- 자동결제는 언제 쓰나요? — 자동결제와 일반 결제의 차이, 빌링키 구조
- 구독 상품 유형별 차이 — 콘텐츠·SaaS·정기배송별 운영 정책
SaaS 월간/연간 요금제, 멤버십, 정기배송 등 반복 결제 서비스를 만들 때예요.
내가 할 일: 관리자(구독 상품 설계) + 백엔드(계약 승인·웹훅 동기화) + Bootpay(자동 과금·재시도)
부트페이 구독은 정기 결제 서비스의 전체 라이프사이클(계약 → 과금 → 해지)을 관리해요.
내가 하는 것
- 구독 상품 설계·등록
- 구독 신청 승인/거절 판단
- 웹훅으로 구독 상태 동기화
- 사용자에게 구독 현황 안내
Bootpay가 알아서 하는 것
- 자동 과금 (매 회차 결제 실행)
- 결제 주기 관리, 실패 재시도
- 해지·일시정지·재개 상태 관리
- 웹훅 알림, 회차별 결제 내역 제공
기능 범위
구독관리는 계약 → 자동 과금 → 운영(정지·해지) 의 전체 라이프사이클을 다뤄요.
플로우
- 구독 계약 / 조회·변경 -> 신규 승인 (승인)
- 구독 계약 / 조회·변경 -> 구독 거절 (거절)
- 신규 승인 -> 자동 과금 / 회차 금액 조정
- 자동 과금 / 회차 금액 조정 -> 일시정지 / 재개 (정지)
- 일시정지 / 재개 -> 자동 과금 / 회차 금액 조정 (재개)
- 자동 과금 / 회차 금액 조정 -> 해지·만료 (해지)
| 영역 | 포함 기능 | 가이드 |
|---|---|---|
| 구독 계약 | 계약 조회, 신규 승인, 거절, 내용 변경 | 계약 조회 · 신규 승인 |
| 구독 회차 | 회차 조회, 회차 금액 조정, 거래 목록 | 회차 조회 · 회차 금액 조정 |
| 고객 요청 | 해지, 일시정지, 재개, 수수료 계산 | 해지 · 일시정지 |
| 관리자 작업 | 관리자 일시정지, 관리자 해지 | 관리자 해지 |
| 요청 처리 | 요청 목록/상세, 승인/거절/철회 | 요청 목록 |
구독 상태 (status)
구독 응답의 status 필드예요. 자주 쓰는 값만 추렸어요 — 전체는 커머스 Enum에 있어요.
| 값 | 키 | 설명 |
|---|---|---|
0 |
contract_requested_completed |
구독 신청 완료, 승인 대기 |
1 |
subscribing |
정상 결제 진행 중 |
-1 |
free_trial |
무료 체험 중 |
-2 |
temporarily_paused |
결제 일시 중단 (재개 가능) |
-3 |
paused_due_to_issue |
결제 실패 등 문제로 중단 |
15 |
auto_terminated |
구독 기간 자연 종료 |
20 |
manual_terminated |
고객이 직접 해지 |
-11 |
admin_terminated |
관리자가 해지 |
-12 |
rejected |
구독 신청 거절 |
라이프사이클
현재 status |
다음 status |
누가 | API | |
|---|---|---|---|---|
contract_requested_completed |
→ | subscribing |
관리자 | 신규 승인 |
contract_requested_completed |
→ | rejected |
관리자 | 구독 거절 |
subscribing |
→ | temporarily_paused |
고객 | 일시정지 |
subscribing |
→ | temporarily_paused |
관리자 | 관리자 일시정지 |
temporarily_paused |
→ | subscribing |
고객 | 재개 |
subscribing |
→ | manual_terminated |
고객 | 해지 요청 |
subscribing |
→ | admin_terminated |
관리자 | 관리자 해지 |
temporarily_paused |
→ | manual_terminated |
고객 | 해지 요청 |
subscribing |
→ | paused_due_to_issue |
자동 | 회차 결제 실패 (subscription.hold_on 웹훅) |
subscribing |
→ | auto_terminated |
자동 | 기간 종료 |
manual_terminated · admin_terminated |
→ | subscribing |
관리자 | 해지 복구 — 공개 API 가 없어요. 아래 참고 |
구독 내용(금액, 상품)을 변경하려면 계약 내용 변경을 사용해요. 상태는 변경되지 않고 결제예정 회차부터 적용돼요.
해지된 구독을 되살리는 일은 부트페이 관리자에서 처리하고, 가맹점이 부를 수 있는 API 가 없어요.
이미 subscription.terminated(또는 .admin_terminated)를 받고 자기 시스템을 해지 처리해 둔 상태라면,
subscription.restored 웹훅을 받아 되살려야 해요. 어떤 회차가 되살아났고 다음 결제일이 언제인지는
그 웹훅 본문의 restore 블록에 담겨요 — 웹훅 처리 가이드를 봐요.
자동 과금은 어떻게 돌아가나요?
구독이 승인되면 Bootpay가 자동으로 매 회차 결제를 실행해요. 가맹점이 매번 결제 API를 호출할 필요가 없어요.
구독 승인
첫 회차가 선결제인 계약이면 Bootpay가 빌링키로 첫 결제를 실행하고, 후불이면 첫 회차 청구를 예약해요.
회차 결제일 도달
자동으로 빌링키 결제를 시도해요.
결제 성공
다음 회차를 예약하고 웹훅을 발송해요.
결제 실패
재시도 스케줄을 실행하고 웹훅을 발송해요.
가맹점은 웹훅을 받아서 서비스 접근을 제어하면 돼요:
| 웹훅 이벤트 | 가맹점이 할 일 |
|---|---|
subscription.approved |
service_active = true (서비스 ON) |
subscription.renewed |
서비스 기간 연장, 다음 결제일 갱신 |
subscription.paused |
서비스 일시 제한 (고객이 스스로 멈춘 상태예요) |
subscription.hold_on |
결제 실패로 자동 중단 — 결제수단 변경을 안내해요 |
subscription.terminated · .admin_terminated |
service_active = false (서비스 OFF) |
subscription.restored |
관리자가 해지를 되돌림 — 서비스 다시 ON |
paused 는 고객이 스스로 멈춘 것이고, hold_on 은 회차 결제가 실패해 서버가 멈춘 것이에요.
결제수단 변경 안내는 hold_on 에만 붙여야 해요. paused 에 붙이면 정상적으로 쉬고 있는 고객에게 오안내가 나가요.
자동 과금의 상세 흐름, 결제 실패 대응 패턴, 유예 기간 설계는 구독 흐름 설계를 참고해요.
구독 회차 (status)
구독이 활성화되면 설정된 주기에 따라 자동으로 결제 회차가 생성돼요.
회차 응답의 status 필드예요. 자주 쓰는 값만 추렸어요 — 전체는 커머스 Enum에 있어요.
| 값 | 키 | 설명 |
|---|---|---|
2 |
bill_ready |
결제 예정 |
1 |
bill_completed |
결제 완료 |
-1 |
bill_failed |
결제 실패 |
5 |
bill_pending |
결제 지연 |
6 |
bill_failure_delayed |
실패 후 재시도 대기 |
10 |
bill_cancelled |
관리자 취소 |
20 |
bill_terminated |
해지로 취소 |
고객 변경 요청
고객이 구독 변경을 요청하면 템플릿 설정에 따라 자동 승인되거나 관리자 승인 후 처리돼요. 재개 요청은 항상 즉시 처리돼요.
요청 유형 (request_type)
| 값 | 키 | 설명 |
|---|---|---|
11 |
request_pause |
일시정지 요청 |
12 |
request_resume |
재개 요청 |
21 |
request_transfer |
이전(승계) 요청 |
31 |
request_purchase |
중도 인수 요청 |
41 |
request_termination |
중도 해지 요청 |
51 |
request_migrate_plan |
플랜 변경 요청 |
요청 상태 (request_status)
| 값 | 키 | 설명 |
|---|---|---|
0 |
request_requested |
요청됨, 관리자 승인 대기 |
1 |
request_approved |
관리자 승인 완료 |
2 |
request_approved_auto |
자동 승인 완료 |
-1 |
request_rejected |
관리자 거절 |
-2 |
request_withdrawn |
고객이 요청 철회 |