개념 배경
이 기능이 왜 필요한지·무엇을 먼저 정할지는 블로그에서 다뤄요.
- 자동결제는 언제 쓰나요? — 자동결제와 일반 결제의 차이, 빌링키 구조
- 구독 상품 유형별 차이 — 콘텐츠·SaaS·정기배송별 운영 정책
정기결제(빌링) 구독의 생성부터 해지까지 전체 흐름을 설명해요.
이럴 때 필요해요: SaaS 월간/연간 요금제, 멤버십, 정기배송 등 반복 결제 서비스를 만들 때
내가 할 일: 관리자(구독 상품 설계) + 백엔드(계약 승인·웹훅 동기화) + Bootpay(자동 과금·재시도)
부트페이 구독은 정기 결제 서비스의 전체 라이프사이클(계약 → 과금 → 해지)을 관리해요.
문서 구조 — 구독 기본 + 상품 4종
내가 하는 것
- 구독 상품 설계·등록
- 구독 신청 승인/거절 판단
- 웹훅으로 구독 상태 동기화
- 사용자에게 구독 현황 안내
Bootpay가 알아서 하는 것
- 자동 과금 (매 회차 결제 실행)
- 결제 주기 관리, 실패 재시도
- 해지·일시정지·재개 상태 관리
- 웹훅 알림, 회차별 결제 내역 제공
구독 처음이라면?
기능 범위
구독관리는 계약 → 자동 과금 → 운영(정지·해지) 의 전체 라이프사이클을 다뤄요.
플로우
- 구독 계약 / 조회·변경 -> 신규 승인 (승인)
- 구독 계약 / 조회·변경 -> 구독 거절 (거절)
- 신규 승인 -> 자동 과금 / 회차 금액 조정
- 자동 과금 / 회차 금액 조정 -> 일시정지 / 재개 (정지)
- 일시정지 / 재개 -> 자동 과금 / 회차 금액 조정 (재개)
- 자동 과금 / 회차 금액 조정 -> 해지·만료 (해지)
| 영역 | 포함 기능 | 가이드 |
|---|---|---|
| 구독 계약 | 계약 조회, 신규 승인, 거절, 내용 변경 | 계약 조회 · 신규 승인 |
| 구독 회차 | 회차 조회, 회차 금액 조정, 거래 목록 | 회차 조회 · 회차 금액 조정 |
| 고객 요청 | 해지, 일시정지, 재개, 수수료 계산 | 해지 · 일시정지 |
| 관리자 작업 | 관리자 일시정지, 관리자 해지 | 관리자 해지 |
| 요청 처리 | 요청 목록/상세, 승인/거절/철회 | 요청 목록 |
구독 상태
| 상태 | 코드 | 설명 |
|---|---|---|
| 대기 | 0 |
구독 신청 후 승인 대기 |
| 구독 중 | 1 |
정상 결제 진행 중 |
| 일시정지 | 2 |
결제 일시 중단 (재개 가능) |
| 해지 | 3 |
중도 해지 완료 |
| 만료 | 4 |
구독 기간 자연 종료 |
라이프사이클
| 현재 상태 | 다음 상태 | 누가 | API | |
|---|---|---|---|---|
| 대기(0) | → | 구독 중(1) | 관리자 | 신규 승인 |
| 대기(0) | → | 거절(-11) | 관리자 | 구독 거절 |
| 구독 중(1) | → | 일시정지(2) | 고객 | 일시정지 |
| 구독 중(1) | → | 일시정지(2) | 관리자 | 관리자 일시정지 |
| 일시정지(2) | → | 구독 중(1) | 고객 | 재개 |
| 구독 중(1) | → | 해지(3) | 고객 | 해지 요청 |
| 구독 중(1) | → | 해지(3) | 관리자 | 관리자 해지 |
| 일시정지(2) | → | 해지(3) | 고객 | 해지 요청 |
| 구독 중(1) | → | 만료(4) | 자동 | 기간 종료 |
구독 내용(금액, 상품)을 변경하려면 내용 변경을 사용해요. 상태는 변경되지 않고 다음 회차부터 적용돼요.
자동 과금은 어떻게 돌아가나요?
구독이 승인되면 Bootpay가 자동으로 매 회차 결제를 실행해요. 가맹점이 매번 결제 API를 호출할 필요가 없어요.
구독 승인
Bootpay가 빌링키로 첫 결제를 실행해요.
회차 결제일 도달
자동으로 빌링키 결제를 시도해요.
결제 성공
다음 회차를 예약하고 웹훅을 발송해요.
결제 실패
재시도 스케줄을 실행하고 웹훅을 발송해요.
가맹점은 웹훅을 받아서 서비스 접근을 제어하면 돼요:
| 웹훅 이벤트 | 가맹점이 할 일 |
|---|---|
subscription.approved |
service_active = true (서비스 ON) |
subscription.paused |
고객에게 결제수단 변경 안내 |
subscription.terminated |
service_active = false (서비스 OFF) |
자동 과금의 상세 흐름, 결제 실패 대응 패턴, 유예 기간 설계는 구독 흐름 설계를 참고해요.
구독 회차
구독이 활성화되면 설정된 주기에 따라 자동으로 결제 회차가 생성돼요.
| 회차 상태 | 코드 | 설명 |
|---|---|---|
| 예정 | 0 |
결제 예정 |
| 성공 | 1 |
결제 완료 |
| 실패 | 2 |
결제 실패 |
| 취소 | 3 |
결제 취소됨 |
고객 변경 요청
고객이 구독 변경을 요청하면 관리자 승인 후 처리돼요.
| 요청 유형 | 코드 | 설명 |
|---|---|---|
| 해지 요청 | 1 |
구독 중도 해지 |
| 구매(인수) 요청 | 2 |
남은 기간 일괄 결제 |
| 이전(승계) 요청 | 3 |
다른 사용자에게 이전 |
| 요청 상태 | 코드 | 설명 |
|---|---|---|
| 대기 | 0 |
승인 대기 중 |
| 확인 대기 | 1 |
사용자 확인 대기 |
| 승인 | 2 |
관리자 승인 완료 |
| 거절 | -1 |
관리자 거절 |
| 철회 | -2 |
고객이 요청 철회 |