Stripe 구독(Subscriptions) 이해하기

Stripe 구독(Subscriptions) 이해하기

고객에게 상품이나 서비스를 매달 반복 제공하려면 '결제가 정상적으로 계속 이어지는지'를 관리해야 해요. Stripe 구독은 이 반복 결제를 생성·청구·상태 전이·재시도까지 자동으로 관리해 주는 기능이에요. 이 페이지에서는 구독 객체가 거치는 수명주기와 상태 값, 그리고 그 뒤에 있는 PaymentIntent·인보이스의 관계를 공식 문서 기준으로 풀어요.

출처: Stripe 공식 문서 — How subscriptions work

구독이란

구독은 고객이 상품·서비스에 접근하기 위해 반복 결제하는 구조예요. 구독을 만들면 Stripe가 인보이스를 자동 생성하고, 결제를 시도하며, 구독 상태를 수명주기 동안 관리해요. 일회성 결제와 달리 미래 청구 주기를 위해 고객·결제 수단 정보를 저장해 둬야 하고, 결제 재시도·연체(dunning)·상태 전이는 Stripe가 처리해요.

구독 수명주기

각 수명주기 단계는 Subscription 객체의 status 변화와 연결돼요. 상태를 이해하면 '언제 접근 권한을 열어줄지, 언제 고객에게 알릴지, 언제 오류를 처리할지'를 알 수 있어요.

  1. 생성 (Create) — 대시보드나 Subscriptions API로 생성해요. 즉시 결제가 필요한 경우 Stripe는 인보이스와 PaymentIntent를 함께 만들고, 첫 결제 전까지 구독 상태는 incomplete였다가 첫 결제 후 active가 돼요. 무료 체험 기간을 두면 초기 상태는 trialing이에요.
  2. 인보이스 처리 (Handle the invoice) — collection_method가 charge_automatically면 만들어진 인보이스가 open 상태로 고객이 23시간 안에 결제할 수 있게 해요. send_invoice면 이메일로 청구서 링크를 보내요.
  3. 결제 확인 (Confirm payment) — 고객이 결제하면 구독은 active, 인보이스는 paid가 되고 invoice.paid 이벤트가 나가요. 23시간 안에 결제하지 않으면 incomplete_expired가 되고 인보이스는 void 처리돼요.
  4. 접근 권한 부여 (Provision access) — 구독이 active가 되면 상품의 기능별 entitlement(접근 권한)가 만들어져요. 웹훅 이벤트로 활성 구독을 추적해 접근을 열어줄 수도 있어요.
  5. 변경 (Update) — 취소 없이 기존 구독을 수정할 수 있어요. 대표적으로 요금제 업그레이드/다운그레이드(change-price), 결제 수집 일시 중지(pause-payment)가 있어요.
  6. 미납 처리 (Handle unpaid) — 인보이스를 못 내면 Stripe가 추가 수집을 멈추고, 청구 주기마다 draft 상태의 인보이스를 계속 생성해요. 구독 status는 past_due 또는 unpaid로 설정에 따라 나뉘어요.
  7. 취소 (Cancel) — 언제든 취소할 수 있고, 기본적으로 새 인보이스 생성이 멈추고 미납 인보이스의 자동 수집이 중지돼요. 취소는 갱신할 수 없는 종료 상태예요.

구독 상태 (Subscription statuses)

Subscription 객체의 status 값과 의미를 정리하면 이래요.

status 의미
trialing 무료 체험 중. 첫 결제 시 자동으로 active로 전이돼요.
active 정상 상태. 단, 이 상태가 모든 미납 인보이스가 결제됐음을 뜻하지는 않아요.
incomplete 23시간 안에 첫 결제를 성공해야 활성화돼요. 인증(3DS 등) 필요 시에도 이 상태예요.
incomplete_expired 초기 결제 실패 후 23시간 안에 성공하지 못한 상태. 청구되지 않아요.
past_due 최신 'finalized' 인보이스 결제가 실패했거나 시도되지 않음. 스마트 재시도 후에도 미납이면 canceled·unpaid·past_due 중 설정대로 전이돼요.
canceled 취소된 종료 상태. 갱신할 수 없어요.
unpaid 최신 인보이스가 미납이지만 구독은 유지. 인보이스는 계속 생성되되 결제 시도를 하지 않아요.
paused 체험 종료 시 기본 결제 수단이 없고 trial_settings.end_behavior.missing_payment_method가 pause일 때. 인보이스를 더 이상 만들지 않아요.

결제 상태와의 관계

구독의 결제 시도는 모두 PaymentIntent가 추적해요. 결제가 있을 때마다 Stripe는 인보이스와 PaymentIntent를 생성하고, PaymentIntent의 status가 인보이스·구독 상태를 결정해요.

결제 결과 PaymentIntent status 인보이스 status 구독 status
성공 succeeded paid active
카드 오류로 실패 requires_payment_method open incomplete
인증 필요로 실패 requires_action open incomplete

결제가 성공하면 invoice.paid 이벤트가 웹훅으로 전달돼요. 카드 오류로 실패하면 고객에게 새 결제 정보를 받아 PaymentIntent를 다시 confirm하고, invoice.payment_failed 이벤트로 재시도 현황을 모니터링해요. 3D Secure(3DS)처럼 고객 인증이 필요한 경우 invoice.payment_action_required 이벤트를 받고, PaymentIntent의 client secret으로 stripe.handleNextAction을 호출해 인증을 이어가요.

한 가지 주의할 점은 즉시 결제 상태를 알 수 없는 결제 수단(예: ACH Direct Debit) 이에요. 이들은 구독이 incomplete를 건너뛰고 바로 active가 될 수 있고, 나중에 결제가 실패하면 인보이스는 void 처리되지만 구독은 active로 남아요 — 접근 제어·재시도 로직을 설계할 때 이 동작을 고려해야 해요.

더 알아보기 (Learn more)