청구서

특정 구매자(회원 또는 비회원)에게 결제를 요청하는 청구서를 만들고 조회합니다. 청구서를 만들면 구매자가 열어 결제할 수 있는 청구서 URL 이 생깁니다.

  • 가격만 청구할 수도 있고, 쇼핑몰에 등록된 상품을 담아 청구할 수도 있습니다. 상품을 담으면 청구 금액은 서버가 상품 판매가로 다시 계산​​합니다(요청의 price·tax_free_price 는 쓰이지 않습니다).
  • 인증은 인증, 오류 형식은 오류를 봅니다.
  • Basic 인증 호출은 멱등 키(Idempotency-Key)를 받습니다.

상태 값

값 뜻
1 결제 대기 (invoice_available)
2 결제 완료 (invoice_order_completed)
3 결제 취소 (invoice_order_cancelled)
-2 기간 만료 (invoice_expired)
-3 판매할 수 없는 상품 포함 (invoice_product_unavailable)
-10 구매자 이탈 (invoice_abandoned)

목록·생성 응답의 status 는 숫자, 상세 응답의 status 는 괄호 안 문자열입니다.

POST /v1/invoices/:id/notify

청구서 알림(알림톡·문자 등)을 다시 보내는 API 입니다.

현재 동작하지 않습니다. 알림 발송 처리가 서버에서 비활성화되어 있어 호출하면 항상 500 SERVER_ERROR 가 옵니다. 청구서 알림은 생성 시 use_notification: true 로 보내세요.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:invoice_notify
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 청구서 ID (invoice_id)
body send_types array [] 발송 수단

응답

정상 응답이 없습니다(위 안내 참고).

오류

HTTP error_code 언제
500 SERVER_ERROR 항상

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성

GET /v1/invoices

이 프로젝트의 청구서 목록을 최신순으로 조회합니다. 삭제된 청구서와 기간 만료·이탈 청구서는 목록에서 빠지고, 상태별 건수(status_counts)에만 잡힙니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:invoice_list
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
query product_type integer 사실상 O 0 청구서 종류. 1 가격만, 2 상품 하나, 3 여러 상품·가격 항목. 보내지 않으면 0 으로 걸러 목록이 비어 옵니다
query keyword string 검색어 (청구서명·상품명·청구서 ID·구매자 정보 부분 일치)
query user_id string 이 회원(대상 회원)의 청구서만. 24자리 ObjectId 형식이면 회원 _id, 아니면 가맹점 회원 ID(ex_uid)로 찾습니다. 이 몰 회원이 아니거나 탈퇴한 회원이면 404. 보내면 응답에 user 가 붙습니다
query cs_type string 기간 검색 기준. c_at 생성일, s_at 발송일, p_at 결제일. 다른 값이면 기간 조건을 무시합니다
query css_at string 기간 시작 (ISO 8601)
query cse_at string 기간 끝 (ISO 8601)
query page integer 1 페이지 번호
query limit integer 24 페이지당 개수

page·limit 은 페이지네이션 공통 규칙이 아니라 받은 값을 정수로 바꿔 그대로 씁니다. 상한이 없고, 0 이하 값은 검사하지 않으니 1 이상을 보내세요.

응답

200 OK

{
  "list": [
    {
      "invoice_id": "66f1c2...",
      "seller_id": "5f...",
      "project_id": "5f...",
      "name": "9월 수강료",
      "product_name": "9월 수강료",
      "type": 1,
      "price": 50000,
      "tax_free": 0,
      "invoice_url": "https://.../i/<clientKey>/66f1c2...",
      "use_redirect": false,
      "status": 1,
      "send_status": 0,
      "send_types": [],
      "user_id": "66a0...",
      "c_at": "2026-09-20T10:00:00+09:00",
      "u_at": "2026-09-20T10:00:00+09:00",
      "user": { },
      "corporate_type": 1,
      "product_ids": ["66b0..."],
      "expired_at": "2026-09-23 00:00:00",
      "use_subscription": false,
      "use_delivery_shipping": false
    }
  ],
  "count": 1,
  "status_counts": { "waiting": 1, "paid": 0, "unpaid": 0 },
  "user": null
}json
필드 타입 설명
list array 청구서 목록. 값이 없는 필드는 빠집니다
list[].invoice_id string 청구서 ID
list[].name / memo / product_name string 청구서명 / 메모 / 상품명
list[].type integer 1 일반, 2 주문 추가 청구, 3 구독 청구, 4 구독 회차 청구
list[].price number 청구 금액
list[].tax_free number 비과세 금액
list[].invoice_url string 구매자가 여는 청구서 URL
list[].use_redirect / redirect_url boolean / string 결제 완료 후 이동 설정
list[].status integer 상태 값
list[].send_status integer 발송 상태. 0 발송 안 함, 1 발송 요청, 10 발송 완료, -1 실패, -10 취소
list[].send_types array 발송 수단
list[].sent_at string 첫 발송 시각
list[].user_id string 구매자 회원 ID
list[].user object 구매자 요약 정보
list[].user_group object 구매자 그룹 정보
list[].corporate_type integer 구매자 유형
list[].product_ids array 담긴 상품 ID
list[].expired_at string 만료 시각 (YYYY-MM-DD HH:mm:ss)
list[].use_subscription boolean 구독 상품 청구서인지
list[].use_delivery_shipping boolean 배송 상품 포함 여부
list[].payment_cycle_type integer 구독 결제 주기
count integer 조건에 맞는 전체 개수
status_counts object 상태를 거르기 전 기준 건수. waiting 결제 대기, paid 결제 완료, unpaid 만료+이탈
user object user_id 로 조회했을 때 그 회원 요약 정보. 아니면 null

오류

HTTP error_code 언제
404 USER_NOT_FOUND (2300) user_id 가 이 몰의 회원이 아님(없는 회원·다른 몰 회원·탈퇴 회원)

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성
  • 2026-09-28 user_id 필터를 대상 회원으로 해석(_id·ex_uid). 찾지 못하면 빈 목록 대신 404 USER_NOT_FOUND

POST /v1/invoices

청구서를 만듭니다. 인증 방식에 따라 응답이 다릅니다.

방식 응답
Basic 인증(서버) JSON (아래 응답​)
client_key 파라미터(브라우저 SDK, Authorization 헤더 없음) 청구서 URL 로 302 리다이렉트

인증

  • 서버 연동: Authorization: Basic base64(clientKey:secretKey) — 인증
  • 브라우저 연동: Authorization 헤더 없이 client_key 파라미터만 보냅니다. secretKey 를 쓰지 않으므로 알림 발송(use_notification)과 가격 조정(products[].price_adjustments)은 무시되고, 오류도 JSON 이 아니라 오류 HTML 페이지​​로 응답합니다.
  • client_key 방식은 비회원(user.membership_type: "guest") 대상 + 자동 로그인 없음 청구서만 만들 수 있습니다. 회원 대상이거나 use_auto_login: true 면 400 API_PARAM_INVALID(reason: merchant_auth_required)로 거절합니다. 공개 client key 만으로 회원의 로그인 세션을 얻을 수 없게 하기 위해서입니다. 회원 청구서·자동 로그인 청구서는 쇼핑몰 서버에서 Basic 인증으로 만드세요.
  • 필요한 scope: user:invoice_create (client_key 방식이면 그 client_key 에 부여된 scope 로 검사)
  • 회원 JWT(Bootpay-User-JWT): 읽지 않습니다. 구매자는 user.user_id 로 지정하며, 이 값은 호출한 회원이 아니라 청구를 받을 대상 회원​​입니다.

요청

위치 이름 타입 필수 기본값 설명
body client_key string client_key 방식이면 O 연동 client key
body request_id string O 가맹점이 정하는 요청 식별값
body user object O 구매자. 아래 표
body name string 청구서명
body memo string 메모
body price number 0 청구 금액. products 를 보내면 서버 계산값으로 대체됩니다
body tax_free_price number 0 비과세 금액. products 를 보내면 서버 계산값으로 대체됩니다
body delivery_price number 0 배송비. products 를 보내면 상품 금액에 더해집니다
body products array 청구할 상품. 아래 표
body expired_at string 3일 뒤 00:00 만료 시각 (YYYY-MM-DD HH:mm:ss 등). 지금보다 뒤여야 합니다
body redirect_url string 결제 완료 후 이동할 URL
body webhook_url string 프로젝트 설정 이 청구서 결제 결과를 받을 웹훅 URL
body header_content_type string 프로젝트 설정 웹훅 형식. application/json·json 또는 application/x-www-form-urlencoded·form·urlencoded
body use_notification boolean false 생성 즉시 구매자에게 알림 발송 (Basic 인증일 때만)
body use_auto_login boolean false 청구서를 연 회원을 자동 로그인 (Basic 인증일 때만. client_key 방식에서 true 면 400)
body usage_api_url string 사용량 구독 상품용 사용량 조회 URL. 상품에 URL 이 없을 때만 필요
body metadata object 가맹점 임의 데이터. 웹훅에 그대로 실립니다
body extra object 추가 옵션. create_order_immediately: true(JSON boolean)면 청구서와 함께 주문서를 바로 만듭니다
body sdk boolean false Basic 인증에서 true 면 응답을 { "redirect_url" } 로 받고 알림 발송을 끕니다

user

이름 타입 필수 설명
user_id string O 회원이면 회원 ID(쇼핑몰 설정에 따라 로그인 ID·이메일도 가능, 이 몰의 사용 중인 회원만), 비회원이면 가맹점이 정한 비회원 식별값
membership_type string guest 면 비회원. 그 외는 회원으로 찾습니다. client_key 방식이면 guest 필수
corporate_type string (회원) individual 또는 corporate. 기본 individual
name / email / phone string (비회원) 구매자 정보. 처음 보는 비회원이면 새로 등록하고, 있으면 갱신합니다

products[]

이름 타입 필수 설명
product_id string O 판매 중인 상품 ID
product_option_id string 옵션 필수 상품이면 O 옵션 ID
quantity integer O 1 이상
duration integer 구독 상품이면 O 구독 기간(개월). 상품에 등록된 기간이어야 합니다. 사용량·수시결제 구독은 필요 없음
price_adjustments array 구독 회차별 가격 조정(Basic 인증일 때만). 각 항목 price_adjustment_id·name·start_at·end_at·cycles[](adjustment_type·value·duration·min_value·max_value·name·description)

구독 상품은 한 청구서에 하나만 담을 수 있습니다.

응답

Basic 인증 — 200 OK, 만든 청구서 (필드는 목록의 list[] 항목과 같습니다)

{
  "invoice_id": "66f1c2...",
  "name": "9월 수강료",
  "price": 50000,
  "invoice_url": "https://.../i/<clientKey>/66f1c2...",
  "status": 1,
  "user_id": "66a0..."
}json
  • sdk: true 면 { "redirect_url": "<청구서 URL>" } 만 옵니다.
  • extra.create_order_immediately: true 면 청구서 대신 만들어진 주문서 정보(주문 웹훅 payload 와 같은 형식, order_url 포함)가 옵니다.

client_key 방식 — 302 Found, Location 이 청구서 URL 입니다.

오류

HTTP error_code 언제
400 INVOICE_TARGET_NOT_FOUND user.user_id 가 없거나 그 회원을 찾을 수 없음
400 INVOICE_REQUEST_ID_BLANK request_id 가 없음
400 INVOICE_EXPIRED_DATE_INVALID expired_at 을 읽을 수 없거나 지금보다 이전
400 USER_CORPORATE_TYPE_INVALID user.corporate_type 이 individual·corporate 가 아님
400 MALL_CORPORATE_TYPE_NOT_ALLOWED 사업자 회원을 받지 않는 쇼핑몰에 corporate 요청
400 USER_GROUP_NOT_FOUND 회원에게 해당 유형의 구매자 그룹이 없음
400 INVOICE_PRODUCT_NOT_FOUND 판매 중이 아니거나 다른 프로젝트의 상품
400 INVOICE_ITEM_QTY_LT_ZERO quantity 가 0 이하
400 INVOICE_PRODUCT_OPTION_ID_REQUIRED 옵션 필수 상품에 product_option_id 가 없음
400 INVOICE_PRODUCT_OPTION_NOT_FOUND 없는 옵션이거나 다른 상품의 옵션
400 INVOICE_SUBSCRIPTION_REQUEST_ONLY_ONE 구독 상품과 다른 상품을 함께 담음
400 INVOICE_PRODUCT_SUBSCRIPTION_DURATION_REQUIRED 구독 상품에 duration 이 없음
400 INVOICE_PRODUCT_SUBSCRIPTION_DURATION_NOT_FOUND 상품에 없는 구독 기간
400 INVOICE_NEED_USAGE_API_URL 사용량 구독 상품에 URL 이 없고 usage_api_url 도 없음
400 PRICE_ADJUSTMENT_* price_adjustments 값이 잘못됨 (이름·ID·주기·날짜·유형·값·기간)
404 PROJECT_SERVER_KEY_INVALID (client_key 방식) 없는 client_key
400 API_PARAM_INVALID (client_key 방식) use_auto_login: true 이거나 user.membership_type 이 guest 가 아님. payload.field 에 use_auto_login·user.membership_type, payload.reason 은 merchant_auth_required

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성
  • 2026-09-28 client_key 방식에서 회원 대상·use_auto_login 청구서 생성을 막음(400 API_PARAM_INVALID). 공개 client key 와 회원 식별자만으로 그 회원의 로그인 세션이 발급되던 경로를 닫기 위한 변경이며, 해당 연동은 서버(Basic) 호출로 옮겨야 합니다

GET /v1/invoices/:id

청구서 하나를 담긴 상품·구매자 정보와 함께 조회합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:invoice_detail
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 청구서 ID (invoice_id)

응답

200 OK

{
  "invoice_id": "66f1c2...",
  "project_id": "5f...",
  "seller_id": "5f...",
  "name": "9월 수강료",
  "product_name": "9월 수강료",
  "type": 1,
  "request_id": "req-20260920-001",
  "metadata": {},
  "status": "invoice_available",
  "expired_at": "2026-09-23T00:00:00+09:00",
  "price": 50000,
  "tax_free_price": 0,
  "delivery_price": 0,
  "product_price": 50000,
  "product_type": 2,
  "order_number": null,
  "user": {},
  "invoice_items": [
    {
      "invoice_item_id": "66f1c3...",
      "product_id": "66b0...",
      "product_option_id": null,
      "name": "수학 단과",
      "price": 50000,
      "quantity": 1,
      "product": {},
      "product_option": null,
      "order_subscription_adjustments": []
    }
  ],
  "invoice_url": "https://.../i/<clientKey>/66f1c2..."
}json
필드 타입 설명
invoice_id string 청구서 ID
name / memo / product_name string 청구서명 / 메모 / 상품명
type integer 청구서 유형 (목록 참고)
request_id string 생성 시 보낸 request_id
metadata object 생성 시 보낸 metadata
status string 상태 값의 문자열
expired_at string 만료 시각 (ISO 8601)
price / tax_free_price / delivery_price / product_price number 청구 금액 / 비과세 / 배송비 / 상품 금액
unit integer 통화
use_subscription / subscription_type / payment_cycle_type 구독 청구서 정보
send_status / send_types / sent_at 발송 정보
pay_at string 결제 시각
order_number string 결제된 주문번호 (결제 전이면 null)
product_type integer 1 가격만, 2 상품 하나, 3 여러 상품
user_id / user string / object 구매자 ID / 구매자 정보 (없으면 {})
invoice_items array 담긴 항목. invoice_item_id·product_id·product_option_id·name·price·origin_price·quantity·total_subscription_duration·status 와 상품 상세(product)·선택 옵션(product_option)·구독 회차 조정(order_subscription_adjustments)
invoice_url string 구매자가 여는 청구서 URL

오류

HTTP error_code 언제
404 INVOICE_NOT_FOUND 없거나 삭제된 청구서
401 INVOICE_DENIED 다른 프로젝트의 청구서

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-08-26 응답에 invoice_url 추가
  • 2026-09-23 문서 최초 작성

함께 보기