개발자센터

구독 운영하기

구독을 시작한 뒤 변경, 일시중지, 결제수단 교체, 결제 실패를 처리하는 방법을 안내합니다.

구독을 시작한 뒤 자주 다루는 상황별 처리 방법입니다. 요청·응답 필드는 구독 API 문서를 참고해 주세요.

청구 규칙

  • 청구 시각: 구독이 시작된 시각이 청구 기준 시각이 됩니다. 매 회차 청구 예정 시각이 지나면 몇 분 안에 인보이스를 만들고 결제합니다.
  • 변경 반영: 상품 가격, 구독 항목, 할인 변경은 모두 다음 회차부터 반영됩니다. 일할 계산은 하지 않으며 이미 결제된 인보이스는 바뀌지 않습니다.
  • 금액: 통화의 최소 단위 정수로 다룹니다. 지원 통화는 KRW·USD·JPY입니다.
  • 0원 청구: 할인으로 청구 금액이 0원이 되면 결제를 시도하지 않고 완료 처리합니다.
  • 결과 미확정: 결제를 요청했지만 결과를 받지 못한 인보이스는 PENDING 상태로 잠시 머물며, 포트원이 결제 상태를 다시 확인해 완료 또는 실패로 정리합니다. 같은 회차가 두 번 결제되지 않습니다.

구독 변경하기

구독 수정 API로 구독 항목, 종료일, 결제 옵션, 인보이스 메일 발송 여부를 바꿀 수 있습니다.

  • 구독 항목(items)은 통째로 교체합니다. 추가·삭제·수량 변경을 한 번에 보내 주세요.
  • nextBillingDate로 정기결제일을 옮길 수 있습니다. 오늘보다 뒤이고 종료일보다 앞이어야 하며, 지정한 날짜가 새 청구 기준일이 됩니다.
  • 결제 옵션(paymentOptions)은 입력한 필드만 고치고, null을 보낸 필드는 지웁니다. 종료(ENDED)된 구독은 고칠 수 없습니다. 고객에게 결제에 쓸 수 있는 빌링키가 있으면 고친 값으로 결제할 수 있는지 미리 확인하고, 결제할 수 없으면 수정하지 않습니다. 다음 결제와 실패한 인보이스의 재시도부터 반영됩니다.

종료일

  • 종료일(endDate)은 구독이 끝나는 날입니다. 종료일 당일과 그 뒤로는 청구하지 않습니다.
  • 마지막 회차를 결제한 뒤에도 종료일까지는 ACTIVE이고, 종료일이 되면 ENDED가 되며 Subscription.Ended 웹훅이 발송됩니다.
  • 종료일이 회차 중간이어도 이미 결제한 금액을 나눠 환불하지 않습니다. 환불이 필요하면 고객사에서 처리해 주세요.

일시중지와 해지

  • 일시중지: ACTIVE 상태의 구독만 일시중지할 수 있습니다. 중지 중에는 인보이스를 만들지 않습니다.
  • 재개: 원래 정기결제일에 다음 회차를 청구합니다. 중지 기간에 지나간 회차는 청구하지 않습니다.
  • 해지: 즉시 종료되며 다시 살릴 수 없습니다.

상품 단위로 청구를 멈추려면 상품 청구 중지를 사용합니다. 그 상품이 담긴 구독은 청구일이 와도 인보이스를 만들지 않고, 청구를 재개하면 그 이후의 첫 청구일부터 다시 청구합니다. 판매를 끝낸 상품은 보관하면 새 구독에 담을 수 없고, 이미 담긴 구독은 계속 청구됩니다.

할인 적용하기

할인은 금액 조건(정률·정액)만 정해 두고, 무엇에 몇 회차 적용할지는 구독에 붙일 때 정합니다.

  • 적용 범위(appliesTo): 인보이스 전체(SUBSCRIPTION) 또는 지정한 상품(PRODUCTS)
  • 지속 방식(duration): 한 번(ONCE), 지정한 회차만큼(CYCLES), 계속(FOREVER)

할인 계산 순서

  1. 상품 지정 할인을 먼저, 구독 전체 할인을 나중에 적용합니다. 같은 범위 안에서는 정률 다음 정액이고, 그 안에서는 구독에 붙인 순서입니다.
  2. 정률 할인은 구독 전체면 합계에 한 번, 상품 지정이면 대상 항목마다 적용합니다. 할인액은 통화의 최소 단위로 반올림합니다.
  3. 정액 할인은 상품 지정이면 대상 항목마다 한 번씩(수량과 무관), 구독 전체면 합계에서 한 번 뺍니다.
  4. 합계는 0원 아래로 내려가지 않습니다. 0원이면 결제 없이 완료 처리합니다.

예를 들어 영어 99,000원, 교재 15,000원에 ① 구독 전체 10%, ② 교재 한정 3,000원이 붙어 있으면 ②로 교재가 12,000원(합계 111,000원)이 되고, 이어서 ①로 합계 99,900원이 됩니다.

적용 범위에 드는 항목이 인보이스에 없으면 그 할인은 반영되지 않고 남은 적용 회차도 줄지 않습니다.

할인은 만든 뒤 이름만 바꿀 수 있습니다. 할인 조건이나 적용 마감일을 바꾸려면 새 할인을 만들어 주세요.

결제수단 바꾸기

새 빌링키를 발급받아 구독 고객 등록 API로 다시 등록하면 고객의 빌링키가 교체됩니다. 고객의 모든 구독이 다음 회차부터 새 빌링키로 결제됩니다. 이전 빌링키는 자동으로 삭제하지 않습니다.

빌링키 삭제 API로 고객의 빌링키를 삭제했다면, 같은 방법으로 새 빌링키를 등록해 주세요. 새 빌링키를 등록하기 전까지는 그 고객으로 구독을 만들 수 없으며, 구독 생성 API가 SUBSCRIPTION_CUSTOMER_HAS_NO_BILLING_KEY로 응답합니다.

고객의 결제수단을 없애려면 결제수단 해지 API를 사용합니다. 해지하면 빌링키가 없는 동안에는 청구일이 와도 인보이스를 만들지 않습니다. 새 빌링키를 등록하면 지난 회차는 청구하지 않고 다음 청구일부터 청구합니다.

결제 실패 처리하기

정기 회차 결제가 실패하면 인보이스는 FAILED 상태가 되고 Invoice.PaymentFailed 웹훅이 발송됩니다. 실패 사유는 인보이스의 payment.failure에 담깁니다. 실패한 인보이스는 자동으로 다시 결제하지 않으므로 아래 중 하나로 처리해 주세요.

  • 다시 결제: 고객에게 결제수단 변경을 안내한 뒤 결제 재시도 API를 호출합니다. 고객의 현재 빌링키로 같은 금액을 결제합니다.
  • 따로 받은 대금 정리: 계좌 입금 등으로 대금을 받았다면 수동 완납 API로 처리합니다.
  • 청구 취소: 청구하지 않기로 했다면 인보이스를 취소합니다. 취소한 정기 회차는 재생성 API로 지금 시점의 상품·할인을 반영해 다시 청구할 수 있습니다.

인보이스가 실패해도 구독의 다음 회차는 예정대로 청구됩니다. 해지한 구독의 실패한 인보이스도 결제 재시도 API로 다시 결제할 수 있습니다. 결제돼도 구독은 다시 시작되지 않으니, 받지 않을 인보이스는 취소해 주세요.

테스트하기

테스트 채널로 구독을 등록하고, 테스트 구독 즉시 청구 API로 정기 회차 결제와 결제 실패를 시험하는 방법은 테스트 결제하기를 참고해 주세요.