종량제 이해하기

종량제는 다른 유형과 청구 구조가 반대예요. 정기구독·정기배송·렌탈은 회차 가격표에 금액이 미리 고정​​되지만, 종량제는 회차마다 부트페이가 가맹점 서버에 사용량을 물어봐서 청구액을 확정해요.

핵심 개념 — 사용량 API

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

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

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

시작 순서

공통 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

응답 (가맹점 → 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

응답 배열에 없는 회차는 금액이 갱신되지 않은 채 조회 완료로 처리돼요. 요청에 온 회차는 빠짐없이 배열에 담아 응답하는 걸 권장해요.

실패와 재시도

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

관련 문서

• 청구 흐름 — 조회 후 결제까지의 스케줄
• 회차 조회 — 확정된 회차 금액 확인

청구 흐름

종량제 회차는 "금액 미정 → 사용량 조회 → 금액 확정 → 결제"의 순서로 굴러가요. 전 과정이 부트페이 스케줄러로 자동화돼 있어요.

회차 한 바퀴

가맹점이 챙길 것

• 집계 마감 — 조회가 오기 전에 그 회차의 사용량 집계가 끝나 있어야 해요. "매월 말일 마감 → 익월 초 청구" 같은 리듬을 설계해요.
• 0원 회차 — 사용량이 없으면 0원을 응답해도 돼요. 종량제는 0원 회차가 허용돼요.
• 회차 보정 — 확정 이후 금액을 바꿔야 하면 회차 금액 조정으로 다음 회차에 반영하는 걸 권장해요.

관련 문서

• 사용량 API 연동 — 요청·응답 규격
• 구독 흐름 설계 — 결제 실패 재시도 공통 흐름

제약과 주의점

종량제는 "금액이 나중에 확정되는" 구조라서, 금액이 미리 정해져 있어야 성립하는 기능들과 조합할 수 없어요.

설정 제약

관련 에러 코드는 에러 코드 사전에서 확인해요.

가격 규칙의 예외

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

운영 주의점

• 결제 주기는 월 단위만 — 사용량 조회 스케줄이 월 주기 회차를 대상으로 돌아서, 템플릿도 월 단위 주기만 저장돼요.
• 사용량 분쟁 대비 — 응답에 usage_items(상세 내역)를 채워두면 회차별 근거가 남아 CS 대응이 쉬워져요.
• 한도 설계 — 폭주 사용으로 결제 한도를 넘는 청구가 나올 수 있어요. 서비스 쪽에서 사용량 상한 또는 구간별 캡을 두는 걸 권장해요.

관련 문서

• 사용량 API 연동 — 응답 규격
• 유형 선택 가이드 — 다른 유형과의 비교