특정 구매자(회원 또는 비회원)에게 결제를 요청하는 청구서를 만들고 조회합니다. 청구서를 만들면 구매자가 열어 결제할 수 있는 청구서 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..."
}jsonsdk: 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 문서 최초 작성
