구독 (Subscription)
정기결제 / 멤버십 / 빌링키 관리 API입니다.
📌 SDK 의 구독 시스템은 빌링키 기반입니다. 콘솔 측 "구독 플랜"이라는 별도 정의는 없으며, 각 구독 생성 시
plan_name,amount,billing_cycle을 그때그때 지정합니다.
빌링키 발급 흐름
1) 빌링키 발급 요청 (서버 → 토스 client key)
typescript
const result = await cb.subscription.issueBillingKey()
console.log(result.toss_client_key, result.customer_key)2) 토스 위젯으로 카드 등록
typescript
import { loadTossPayments } from '@tosspayments/payment-sdk'
const tossPayments = await loadTossPayments(result.toss_client_key)
await tossPayments.requestBillingAuth('카드', {
customerKey: result.customer_key,
successUrl: 'https://mysite.com/billing/success',
failUrl: 'https://mysite.com/billing/fail'
})3) 등록 완료 콜백에서 빌링키 확정
typescript
// successUrl 콜백 페이지에서
const params = new URLSearchParams(window.location.search)
const billingKey = await cb.subscription.confirmBillingKey({
customer_key: params.get('customerKey')!,
auth_key: params.get('authKey')!,
customer_email: '[email protected]',
customer_name: '홍길동',
is_default: true
})
console.log('빌링키 ID:', billingKey.billing_key_id)빌링키 관리
typescript
// 목록 조회
const { billing_keys } = await cb.subscription.listBillingKeys()
// 특정 고객만
const my = await cb.subscription.listBillingKeys('cust_xxx')
// 단건 조회
const bk = await cb.subscription.getBillingKey('bk_xxx')
// 수정 (별칭 / 기본 카드 변경)
await cb.subscription.updateBillingKey('bk_xxx', {
card_nickname: '주 결제 카드',
is_default: true
})
// 삭제
await cb.subscription.deleteBillingKey('bk_xxx')구독 생성
typescript
const subscription = await cb.subscription.create({
billing_key_id: 'bk_xxxxx',
plan_name: '프리미엄 플랜',
amount: 9900,
billing_cycle: 'monthly', // 'monthly' | 'yearly' 등
billing_day: 15, // 매월 결제일 (선택)
trial_days: 7 // 무료 체험 일수 (선택)
})
console.log(subscription.id, subscription.status)구독 목록 / 단건 조회
typescript
const { subscriptions, total } = await cb.subscription.list({
status: 'active',
limit: 10,
offset: 0
})
const sub = await cb.subscription.get('sub_xxx')구독 수정 / 취소 / 일시정지 / 재개
typescript
// 플랜 변경 (이름과 금액 같이 변경)
await cb.subscription.update('sub_xxx', {
plan_name: '엔터프라이즈 플랜',
amount: 29900
})
// 일시정지
await cb.subscription.pause('sub_xxx', { reason: '고객 요청' })
// 재개
await cb.subscription.resume('sub_xxx')
// 취소 (현재 기간 종료 후)
await cb.subscription.cancel('sub_xxx', {
reason: '서비스 불만족'
})
// 즉시 취소
await cb.subscription.cancel('sub_xxx', {
reason: '즉시 해지 요청',
immediate: true
})구독 결제 이력 조회
typescript
const { payments } = await cb.subscription.listPayments('sub_xxx', {
limit: 10
})
payments.forEach((p) => {
console.log(p.amount, p.status, p.paid_at)
})빌링키로 즉시 결제 (구독 외 일회성)
typescript
const result = await cb.subscription.chargeWithBillingKey({
billing_key_id: 'bk_xxx',
amount: 15000,
order_name: '추가 결제'
})
if (result.status === 'done') {
console.log('결제 완료!')
}