종량제

종량제(usage_based_subscription)는 사용량에 따라 회차 청구액이 결정되는 구독 유형입니다. 다른 유형은 회차 가격표에 금액이 미리 고정​​되지만, 종량제는 회차마다 부트페이가 가맹점 서버에 사용량을 조회해 청구액을 확정합니다. 유형 구분은 유형 선택 가이드를 참고합니다.

사용량 API 개요

종량제 구독을 만들려면 상품에 사용량 API URL(usage_api_url)이 반드시 있어야 합니다. 이 URL은 가맹점 서버의 엔드포인트로, 부트페이가 회차 결제 전에 호출해서 그 회차의 청구액을 받아 갑니다.

결제 예정일 접근 → Bootpay가 usage_api_url 호출 → 가맹점이 금액 응답 → 회차 금액 확정 → 자동 결제

구현 규격은 사용량 API 연동에서 자세히 다룹니다.

시작 순서

과금 모델 설계

단가표(건당 요금, 구간 요금)를 정합니다. 금액 계산은 가맹점 서버가 하고, 부트페이는 최종 금액만 받습니다.

사용량 API 구현

부트페이의 조회 요청에 금액을 응답하는 엔드포인트를 만듭니다. 사용량 API 연동

상품 등록

종량제 템플릿을 상품에 적용하고, 상품의 usage_api_url 에 사용량 API 주소를 넣습니다. 종량제는 상품가 0원이 허용됩니다.

신청 → 승인 → 자동 청구

승인 후에는 매 회차 사용량 조회 → 결제가 자동으로 반복됩니다. 청구 흐름

공통 API 바로가기

하고 싶은 것 문서
계약 목록·상태 조회 계약 조회
회차·확정 금액 확인 회차 조회
신청 승인·거절 신청 관리
일시정지·재개·해지 일시정지 · 해지

사용량 API 연동

사용량 API는 부트페이가 가맹점 서버를 호출하는 방향입니다. 가맹점이 엔드포인트를 열어두면, 회차 결제 전에 부트페이가 청구 대상 회차 목록을 보내고 가맹점은 각 회차의 금액을 응답합니다.

상품 등록의 usage_api_url에 이 엔드포인트 주소를 등록합니다.

호출 시점

  • 결제 예정일이 다가오면(약 7일 전부터) 부트페이가 조회를 시작합니다. 단, 그 회차의 이용 기간이 끝난 뒤에만 조회합니다.
  • 아직 확정되지 않았거나 이전 조회가 실패한 회차가 대상입니다.
  • 같은 프로젝트·같은 상품의 회차는 한 요청에 묶여서 올 수 있습니다 — 응답도 배열로 돌려줍니다.

요청 (Bootpay → 가맹점)

usage_api_url로 JSON POST가 옵니다.

{
  "bills": [
    {
      "order_subscription_id": "6650f1a2b3c4d5e6f7a8b9c0",
      "order_subscription_bill_id": "6650f1a2b3c4d5e6f7a8b9c1"
    },
    {
      "order_subscription_id": "6650f1a2b3c4d5e6f7a8b9c2",
      "order_subscription_bill_id": "6650f1a2b3c4d5e6f7a8b9c3"
    }
  ]
}json
파라미터 타입 필수 설명
bills Array 필수 청구액을 확정할 회차 목록
  └─ order_subscription_id String 필수 구독 계약 ID
  └─ order_subscription_bill_id String 필수 회차 ID — 응답에서 이 값으로 짝을 맞춥니다

응답 (가맹점 → Bootpay)

HTTP 200 + JSON 배열​​로 응답합니다. 배열이 아니거나 200이 아니면 실패로 처리됩니다.

[
  {
    "order_subscription_bill_id": "6650f1a2b3c4d5e6f7a8b9c1",
    "price": 132000,
    "tax_free_price": 0,
    "quantity": 1200,
    "one_unit_price": 110,
    "usage_items": [
      {
        "item_code": "api_call",
        "item_name": "API 호출",
        "unit_price": 110,
        "quantity": 1200,
        "price": 132000
      }
    ]
  }
]json
필드 타입 필수 설명
order_subscription_bill_id String 필수 요청으로 받은 회차 ID 그대로
price Integer 필수 이 회차에 청구할 최종 금액
tax_free_price Integer 선택 최종 금액 중 비과세 금액
quantity Integer 선택 총 사용량 (기본 1)
one_unit_price Integer 선택 단가
one_unit_tax_free_price Integer 선택 단가 중 비과세
origin_price Integer 선택 할인 전 원금액
origin_tax_free_price Integer 선택 할인 전 비과세 금액
usage_items Array 선택 사용량 상세 내역 — 고객 안내·정산 근거로 저장됩니다
item_code String 선택 과금 항목 코드
item_name String 선택 과금 항목 이름
unit_price Integer 선택 항목 단가
quantity Integer 선택 항목 사용량
price Integer 선택 항목 금액
tax_free_price Integer 선택 항목 비과세 금액
usage_summary Object 선택 요약 — 생략하면 usage_items 기준으로 자동 생성됩니다

응답 배열에 없는 회차는 금액이 갱신되지 않은 채 조회 완료로 처리됩니다. 요청에 온 회차는 빠짐없이 배열에 담아 응답합니다.

실패와 재시도

상황 처리
HTTP 200이 아닌 응답 해당 회차 조회 실패 처리 후 다음 스케줄에 재시도
응답이 JSON 배열이 아님 위와 동일
타임아웃·네트워크 오류 위와 동일

결제 예정일까지 조회가 계속 실패하면 회차 금액을 확정할 수 없습니다. 사용량 API는 멱등하게​(같은 회차에 같은 금액을 응답) 구현하고, 5xx 없이 빠르게 응답하도록 유지합니다.

구현 체크리스트
  • 요청 body의 bills 배열 순회 — 단건이 아니라 복수 회차가 올 수 있습니다.
  • 회차 ID 기준으로 사용량을 집계하는 조회 키(계약 ID ↔ 가맹점 서비스 계정 매핑)를 준비합니다.
  • 응답 금액은 정수(원 단위)입니다.
  • 집계 마감 전에 호출이 올 수 있으므로, 조회 시점까지의 확정 사용량을 응답합니다.

관련 문서


청구 흐름

종량제 회차는 "금액 미정 → 사용량 조회 → 금액 확정 → 결제" 순서로 진행되며, 전 과정을 부트페이 스케줄러가 자동으로 처리합니다.

회차 한 바퀴

회차 생성

주기에 따라 다음 회차가 만들어집니다. 이 시점의 금액은 아직 확정 전입니다.

사용량 조회

결제 예정일이 다가오면(약 7일 전부터, 회차 이용 기간이 끝난 뒤) 부트페이가 사용량 API를 호출합니다. 실패하면 다음 스케줄에 다시 시도합니다.

금액 확정

응답받은 금액·사용량 내역이 회차에 기록됩니다. 회차 조회에서 확정 금액과 사용량 내역을 확인할 수 있습니다.

자동 결제

결제일에 확정 금액으로 빌링키 결제가 실행됩니다. 성공·실패 처리는 다른 유형과 같습니다. 실패 시 재시도 스케줄과 웹훅이 동작합니다.

가맹점 처리 사항

  • 집계 마감 — 조회가 오기 전에 그 회차의 사용량 집계가 끝나 있어야 합니다.
  • 0원 회차 — 사용량이 없으면 0원을 응답해도 됩니다. 종량제는 0원 회차가 허용됩니다.
  • 회차 보정 — 확정 이후 금액 변경은 회차 금액 조정으로 다음 회차에 반영합니다.

관련 문서


제약과 주의점

종량제는 금액이 나중에 확정되므로 금액이 미리 정해져야 하는 기능과 함께 쓸 수 없습니다.

설정 제약

제약 이유
상품 usage_api_url 필수 사용량을 조회할 곳이 없으면 청구액을 확정할 수 없습니다. 종량제 템플릿을 붙인 상품을 이 값 없이 저장하면 SUBSCRIPTION_SETTIGN_NEED_USAGE_API_URL 에러가 발생합니다.
월 단위 결제 주기만 사용량 조회 스케줄이 월 주기 회차를 대상으로 돕니다. 다른 주기로 템플릿을 저장하면 SUBSCRIPTION_SETTING_USAGE_CYCLE_MONTHLY_ONLY 에러가 발생합니다.
선불(선급금) 불가 금액이 확정되기 전이라 미리 받을 금액을 정할 수 없습니다.
쿠폰 적용 불가 할인 대상 금액이 신청 시점에 존재하지 않습니다. 할인은 사용량 API 응답에 할인 반영 금액을 주거나 회차 금액 조정으로 처리합니다.

관련 에러 코드는 에러 코드 사전에서 확인합니다.

가격 규칙의 예외

다른 유형은 회차 중 최소 한 회차가 유료여야 하지만, 종량제는 상품가·전 회차 0원이 허용​​됩니다. 실제 금액은 매 회차 사용량으로 결정되기 때문입니다.

운영 주의점

  • 결제 주기는 월 단위만 — 사용량 조회 스케줄이 월 주기 회차를 대상으로 돌아서, 템플릿도 월 단위 주기만 저장됩니다.
  • 사용량 상세 내역 — 응답의 usage_items 는 회차별 근거로 저장됩니다.
  • 결제 한도 — 사용량이 많으면 결제 한도를 넘는 청구가 나올 수 있습니다. 상한은 가맹점 서비스에서 둡니다.

관련 문서

함께 보기