스텝페이에서 구독(Subscription) 이란 일정 주기로 가격이 결정된 RECURRING 타입의 주문(Order) 을 생성하는 엔티티입니다.
구독(Subscription)은 RECURRING_INITIAL 타입의 주문(Order)이 결제되면 자동으로 생성되며 이후 주기적으로 RECURRING 타입의 주문(Order)을 생성하기
때문에 RECURRING_INITIAL 타입의 주문은 구독과 일대다 관계를 가짐과 동시에, 구독은 RECURRING 타입의 주문과 일대다 관계를 가집니다.
RECURRING_INITIAL 타입의 주문(Order) 을 결제할 때 고객이 사용한 결제수단이 구독(Subscription) 의 결제수단으로 등록되며, 갱신 결제에 해당 결제수단이 이용됩니다. 결제 수단 변경을
하려면 고객이 변경하고자 하는 결제수단으로 다시 결제를 진행해야 합니다.
연관 가이드
사전 준비 작업
- 구독 가격 플랜 담긴 주문이 생성되어 있어야 합니다.
- 정기 결제 가능한 PG 가 연동되어 있어야 합니다.
- [설정 → 결제 설정 → PG 연동관리] 메뉴에서 테스트 모드로 추가할 수 있습니다.
- 실 결제를 위해서는 PG사와 빌링 결제 계약이 필요합니다.
구독의 생성
FLAT, BUNDLE, USAGE_BASED, UNIT_BASED 타입의 가격 플랜이 포함된 주문을 결제하면 구독이 자동으로 생성됩니다.구독은 고객과의 계약이기 때문에 API 를 통해 생성할 수 없으며, 최초 1번 고객이 수동으로 결제하는 방법으로만 생성할 수 있습니다.
구독의 주기는 가격 플랜의 속성과 상품의 무료 체험과 같은 일부 속성들에 의해 결정됩니다.
만약 여러 개의 주문 아이템이 포함되어 있는
RECURRING_INITIAL 주문이 결제되면 구독 묶음을 결정하는 요소에 의해 구독이 여러개 생길 수 있습니다.
다음은 주문 아이템들이 구독 묶음으로 결정되는 속성들입니다.
| 필드 | 설명 |
|---|---|
| Current Period End Date | 현재 결제 주기의 종료 날짜 (예: 첫 번째 주기 종료 날짜) |
| Interval | 구독 주기 (예: 1개월) |
| Expiry Date | 서비스나 구독이 만료되는 날짜 (특정 날짜에 만료되는 경우) |
| Provide Start Day | 주기 내에서 서비스 제공이 시작되는 날 (해당하는 경우) |
| Billing Date | 결제 주기와 관계없이 매월 특정한 결제일 (예: 매월 5일 결제) |
| Trial End | 무료 체험 기간이 끝나는 날짜 |
| Expiry Recurring Count | 만료되기 전까지 허용된 최대 갱신 횟수 (예: 10번 갱신 후 만료) |
| Claim Method Type | 결제 방식 (선불 또는 후불) |
구독의 생명주기
구독의 생명주기는 구독의 상태가 어떻게 변하는지를 나타냅니다. 각 상태는 특정 이벤트에 의해 변경될 수 있습니다. 구독의 생명주기는 스텝페이에서 자동으로 관리되지만 연동 개발하고 있는 시스템과 통합하려면 구독의 상태 변경과 시스템 상태를 동기화 해야합니다. 예를들면, 구독이 일시정지 되었을 때 해당 고객의 SaaS 소프트웨어의 사용이 중지되어야 할 수 있습니다. 시스템과 통합하는 자세한 방법은 연동 가이드를 참고하세요. 다음은 구독의 상태 및 이벤트에 대한 개요입니다.구독 상태
ACTIVE: 구독이 활성화 상태이며, 사용자가 서비스를 이용할 수 있는 상태입니다.UNPAID: 스케쥴 된 주문이 결제 실패하여 서비스 이용이 일시 중지된 상태입니다. 구독이 이 상태가 되면 복구 프로세스가 동작하게 됩니다.PENDING_CANCEL: 사용자가 구독 취소를 요청했으나, 아직 최종 취소 상태로 전환되지 않은 상태입니다. 구독 취소 API 또는 스텝페이 포탈에서 구독 취소 옵션으로 특정일 취소 또는 현제 주기 종료 후 취소 옵션을 선택하면 구독이 이 상태로 변경됩니다.CANCELED: 구독이 최종적으로 취소된 상태입니다. 구독 취소 API 또는 스텝페이 포탈에서 구독 취소 옵션으로 즉시 취소 옵션을 선택하거나 취소 요청일이 되면 구독이 이 상태로 변경됩니다. 취소된 구독은 다시 복구될 수 없습니다.PENDING_PAUSE: 사용자가 구독 일시정지를 요청했으나, 아직 최종 일시정지 상태로 전환되지 않은 상태입니다. 구독 일시정지 API 또는 스텝페이 포탈에서 구독 일시정지 옵션으로 특정일 일시정지 또는 현제 주기 종료 후 일시정지 옵션을 선택하면 구독이 이 상태로 변경됩니다.PAUSE: 구독이 일시 중지된 상태입니다.EXPIRED: 복구 프로세스 에도 구독 복구를 실패하거나 만료일을 지정한 구독의 경우 만료일이 도래하면 구독이 만료된 상태입니다. 만료된 구독은 다시 복구될 수 없습니다.
취소 또는 만료된 구독은 다시 복구될 수 없습니다.👉 구독 상태 다이어그램 을 확인해보세요.
주문 취소가 구독에 미치는 영향
구독을 생성한 주문 (RECURRING_INITIAL) 이 취소되면 해당 주문에 의해 생성된 모든 구독이 취소됩니다. 하지만 구독이 취소되어도 해당 구독과 관련된 주문이 환불되는 것은 아닙니다. 구독 취소와 함께 이미 결제된 주문을 취소하기 위해서는 별도로 주문 취소 API를 사용해야 합니다. 이와 반대로 구독에 의해 생성된 주문(RECURRING) 은 환불 혹은 취소되어도 구독은 취소되지 않습니다. 주문 환불과 함께 구독 또한 취소 하려면 별도로 구독 취소 API를 사용해야 합니다.선불 구독과 후불 구독
선불 구독과 후불 구독은 주기적으로 RECURRING 주문을 생성한다는 점에서는 동일하지만 동작 방식에 약간의 차이가 있습니다. 선불 구독은 만료되거나 취소될 때 추가적인 결제가 일어나지 않지만 후불 구독의 경우 마지막 RECURRING 주문을 생성한 뒤 취소 혹은 만료됩니다. 또 한가지 다른 점은 갱신 횟수를 세는 방식입니다. 구독 상세 API를 통해 알아낼 수 있는 갱신 횟수(recurringCount)가 구독 최초 생성 시 선불 구독의 경우 1, 후불 구독의 경우 0으로 시작됩니다.
갱신 실패에 대한 재시도 정책
카드 유효기간 만료, 잔액 부족 등의 사유로 갱신 결제가 실패한 경우 복구 프로세스가 시작됩니다. 구독이 결제 실패되면 구독은 그 즉시UNPAID 상태가 됩니다.
기본적으로 복구 프로세스는 최초 결제 실패 일로부터 1일, 3일, 5일, 10일, 14일 후에 결제를 재시도 하는 정책으로 동작합니다. 복구 프로세스를 통해 구독이 복구되면 구독의 상태는 ACTIVE 상태로 돌아옵니다.
연동하는 시스템은 구독의 상태를 웹훅을 통해 관찰하고 있어야 하며 구독을 복구하기 위해 고객의 결제 수단을 변경하는 방법을 제공해야 할 수도 있습니다.