결제 준비(주문서 생성), 주문 목록·상세 조회, 발주(배송) 처리, 구매자용 결제 결과 조회를 다룹니다. 주문 취소·구매확정·결과 페이지용 조회는 주문 처리를 봅니다.
- 경로의
:id는 모두 주문번호(order_number)입니다. 내부 ID(order_id)가 아닙니다. - 인증·오류 형식·멱등 키 같은 공통 내용은 인증, 오류, 멱등 키, 회원 JWT를 봅니다.
- 응답의
status·receipt_status같은 상태 값은 숫자가 아니라 영문 enum 문자열로 나갑니다(예:payment_completed).
주문 상태 (status)
| 값 | 뜻 |
|---|---|
order_pending |
주문서만 생성됨(결제 전) |
payment_pending |
결제창 진입·가상계좌 입금 대기 |
payment_completed |
결제 완료 |
payment_confirm_ready |
승인 전(분리 승인 대기) |
payment_delayed |
지연 결제 |
subscription_request_completed / subscription_pending |
구독 신청 완료 / 구독 대기 |
purchase_confirmed |
구매 확정 |
cancellation_completed / return_completed / exchange_completed |
취소 / 반품 / 교환 완료 |
subscription_terminated |
구독 종료 |
order_expired |
결제 시간 만료 |
payment_failed / payment_authorization_failed |
결제 실패 / 결제 승인 실패 |
subscription_error / subscription_server_error |
구독 결제 오류 |
order_abandoned |
결제창 이탈로 닫힘 |
POST /v1/orders/prepare
결제 준비 — 주문서를 만들고 결제에 쓸 주문번호(또는 결제 페이지 URL)를 돌려줍니다. 결제는 이 주문번호로 진행합니다.
두 가지 입력 방식이 있습니다.
- 견적 방식 (신규 연동 권장): 먼저 장바구니 견적(
POST /v1/cart/order-preview, 장바구니)으로quote_token을 받고, 그 토큰을 보냅니다. 상품·수량·배송 방식·금액은 서버가 서명한 견적 토큰의 값만 씁니다. 요청의products·price는 결제 준비에 쓰이지 않고, 보낸 경우 견적과 같은지 확인하는 데만 씁니다. 회원이 견적에cart_item_id를 보냈다면 결제 완료 때 그 장바구니 줄에서 결제 수량만큼 자동으로 빠집니다. - 호환 방식 (기존 연동):
quote_token없이products·price를 보냅니다. 서버가 현재 상품 가격으로 다시 계산해price와 다르면 거절합니다.
어느 방식이든 금액의 기준은 서버 계산값입니다. 클라이언트가 보낸 금액으로 결제 금액이 정해지지 않습니다.
인증
Authorization: Basic base64(clientKey:secretKey)— 인증- 또는
Authorization헤더 없이client_key파라미터(공개 클라이언트 키)만 보내 호출할 수 있습니다(브라우저·SDK 용). 이때 오류는 JSON 이 아니라 HTTP 200 의 HTML 페이지로 옵니다. 페이지는 SDK 창 안이면 SDK 오류 이벤트를 보내고, 아니면redirect_url로error_code·message쿼리를 붙여 이동합니다. - 필요한 scope:
user:order_prepare - 회원: JWT 또는 user_id 선택 —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정) — 회원 JWT. 지정하면 그 회원의 주문, 없으면 비회원 주문입니다.- JWT 가 무효·만료여도 오류를 내지 않고 비회원으로 처리합니다(아래 자동 로그인 URL 요청만 예외). 이때
user_id를 함께 보냈으면 비회원 대신 그user_id회원으로 처리합니다. user_id는 secretKey 인증(Basic·Bearer)에서만 받습니다.client_key만으로 부르며user_id를 보내면400 API_PARAM_INVALID(payload.reason: "merchant_auth_required") 입니다.- 견적(
POST /v1/cart/order-preview)과 같은 방식으로 회원을 보내세요. 견적은user_id, 결제 준비는 회원 없이 부르는 식으로 구매자가 달라지면403 ORDER_QUOTE_SESSION_MISMATCH입니다. - 자동 로그인 URL(
use_auto_login+response_type=url)은 회원 JWT 가 있어야 만듭니다.user_id로만 지정하면401 USER_SESSION_INVALID입니다.
- JWT 가 무효·만료여도 오류를 내지 않고 비회원으로 처리합니다(아래 자동 로그인 URL 요청만 예외). 이때
Bootpay-Device-UUID헤더: 비회원 구매자를 기기 단위로 구분합니다. 견적 방식에서는 견적을 받을 때와 같은 값을 보내야 합니다.
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| header | Idempotency-Key | string | 구매자 범위 멱등 키. 아래 멱등 키 참고 | ||
| body | quote_token | string | 견적 토큰. 키가 있으면(빈 문자열 포함) 견적 방식으로 처리합니다 | ||
| body | products | array | 호환 방식에서 O | 구매 상품 목록 (아래 표) | |
| body | price | number | 호환 방식에서 O | 첫 결제로 낼 상품 금액 합계(배송비 제외). 0 미만이면 400 | |
| body | uct | integer | 회원이면 O | 회원 주문 유형. 1 개인, 2 기업, 3 부서. 비회원은 보지 않습니다 |
|
| body | delivery_type | integer | 배송 방식. 1 택배, 2 직접 배송, 3 퀵, 4 방문 수령. 견적 방식은 견적 값을 씁니다 |
||
| body | invoice_id | string | 이 주문을 연결할 청구서 ID. 청구서의 회원 정보가 주문에 들어갑니다 | ||
| body | response_type | string | url 이면 결제 페이지 URL 을 돌려줍니다. 그 외에는 주문 정보를 돌려줍니다 |
||
| body | redirect_url | string | 결제 완료 후 이동할 주소. 견적 방식에서는 쇼핑몰에 등록된 https 도메인만 받습니다(부트페이 쇼핑몰 도메인, 쇼핑몰 서브도메인, 관리자에 등록한 도메인, 연결 완료된 커스텀 도메인) | ||
| body | use_auto_login | boolean | false |
true 이고 response_type=url 이면 결제 페이지에 회원이 로그인된 채로 들어가는 URL 을 만듭니다. 유효한 회원 JWT 가 필수입니다 |
|
| query | client_key | string | Authorization 없이 호출할 때의 클라이언트 키 |
products[] 항목
| 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| product_id | string | O | 상품 ID |
| option.product_option_id | string | 선택 옵션 ID. 옵션이 필수인 상품이면 반드시 보냅니다 | |
| quantity | integer | O | 수량 |
| period | integer | 구독 상품의 이용 기간(개월). 기간별 가격을 씁니다 | |
| period_label | string | 구독 기간 표시 문구 | |
| cart_item_id | string | 장바구니 항목 ID(주문에 기록만 합니다). 결제 후 장바구니를 정리하려면 견적의 cart_items[].cart_item_id 로 보내세요 |
견적 방식에서 products 를 함께 보내면 (상품 ID, 옵션 ID)별 수량 합과 price 가 견적과 같아야 합니다. 다르면 400 ORDER_QUOTE_TOKEN_INVALID(payload.reason: "quote_request_mismatch")입니다.
멱등 키
이 API 는 공통 멱등 규칙 대신 아래 구매자 범위 규칙을 따릅니다.
- 범위: 프로젝트 + 구매자 + HTTP 메서드 + 경로 +
Idempotency-Key. 구매자는 회원이면 JWT 또는user_id로 정한 회원, 비회원이면Bootpay-Device-UUID로 정합니다. 다른 회원·다른 기기는 같은 키를 써도 서로의 결과를 보지 않습니다.Bootpay-Device-UUID없이 호출한 비회원 요청은 모두 하나의 "비회원" 구매자로 묶입니다. 비회원 요청에는 기기 UUID 를 보내거나 요청마다 새 키를 쓰세요.- 같은 회원이 갱신된 JWT 로 재시도해도 같은 요청으로 봅니다.
- 같은 범위·같은 입력: 처음 요청이 끝났으면 결제 준비를 다시 하지 않고 처음 응답 본문을
200으로 돌려줍니다. 견적이 만료되거나 가격이 바뀐 뒤의 재시도도 원래 결과를 받습니다. - 같은 범위·다른 입력:
409 IDEMPOTENCY_REQUEST_MISMATCH. 원래 결과(주문번호·URL)는 싣지 않습니다. 새 견적 토큰으로 결제할 때는 새 키를 쓰세요.- 입력 비교 대상:
price,products,uct,delivery_type,invoice_id,response_type,redirect_url,use_auto_login,quote_token. 객체의 키 순서는 무시하지만, 값의 타입이 바뀌면(예:1→"1") 다른 입력으로 봅니다. 재시도는 같은 본문을 그대로 보내세요.
- 입력 비교 대상:
- 처리 중: 같은 요청이 아직 처리 중이면 최대 3초 기다려 그 결과를 돌려줍니다. 그래도 안 끝나면
409 IDEMPOTENCY_REQUEST_IN_PROGRESS와Retry-After: 1헤더(payload.retry_after: 1)를 줍니다. - 실패한 요청: 결제 준비가 오류로 끝나면 그 오류는 저장하지 않습니다. 같은 키로 재시도하면 처음부터 다시 실행합니다.
- 처리하던 서버가 중단돼 60초 안에 끝나지 않은 요청은 같은 입력의 재시도가 이어받아 실행합니다.
- 기록은 처음 요청 시각부터 7일이 지나면 지워지고, 그 뒤 같은 키는 새 요청으로 처리됩니다.
- 자동 로그인 URL 응답을 재생할 때는 URL 을 저장해 두지 않고, 이번 요청의 회원 JWT·기기로 다시 만듭니다. 다른 회원의 JWT 로는 재생되지 않습니다(
401 USER_SESSION_INVALID).
키를 보내지 않으면 매번 새 주문서를 만듭니다.
응답
200 OK — 응답에는 Cache-Control: no-store 헤더가 붙습니다.
response_type 이 url 이 아닐 때
{
"order_id": "66f1c2...",
"order_number": "2409231234567",
"order_name": "기본 티셔츠 외 1건",
"price": 32000,
"expired_at": "2026-09-23T12:30:00+09:00",
"result_token": "r1.eyJ2Ijo...",
"result_token_expires_at": "2026-09-24T03:00:00Z"
}jsonresponse_type=url 일 때
{
"order_number": "2409231234567",
"url": "https://..."
}json| 필드 | 타입 | 설명 |
|---|---|---|
| order_id | string | 주문서 ID |
| order_number | string | 주문번호. 이후 조회·결제에 씁니다 |
| order_name | string | 주문명 |
| price | number | 서버가 계산한 결제 금액 |
| expired_at | string | 결제 가능 기한(ISO 8601). 쇼핑몰의 결제 제한 시간 설정(기본 30분)을 따릅니다 |
| url | string | 결제 페이지 주소. use_auto_login 이면 회원 세션이 담긴 주소이므로 로그·캐시·공유 링크에 남기지 마세요 |
| result_token | string | 견적 방식 비회원에게만 옵니다. 구매자 결제 결과 조회용 토큰(24시간 유효) |
| result_token_expires_at | string | result_token 만료 시각(UTC ISO 8601) |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | ORDER_QUOTE_TOKEN_INVALID |
견적 토큰 형식·서명이 잘못됨, 또는 요청 products·price 가 견적과 다름(payload.reason: "quote_request_mismatch") |
| 400 | ORDER_QUOTE_TOKEN_EXPIRED |
견적 토큰 유효 시간(10분)이 지남. 다시 견적을 받으세요 |
| 403 | ORDER_QUOTE_SESSION_MISMATCH |
견적을 받은 쇼핑몰·구매자(회원 JWT 또는 Bootpay-Device-UUID)와 지금 요청이 다름 |
| 409 | ORDER_QUOTE_PRICE_CHANGED |
견적 이후 상품 가격·배송비가 바뀜. 다시 견적을 받으세요 |
| 442 | CART_HAS_UNAVAILABLE_ITEMS |
견적 상품 중 지금 구매할 수 없는 상품이 있음. payload.errors[] 에 index·product_id·product_option_id·reason |
| 400 | ORDER_PREPARE_REDIRECT_URL_NOT_ALLOWED |
(견적 방식) redirect_url 이 등록된 https 도메인이 아님 |
| 409 | IDEMPOTENCY_REQUEST_MISMATCH |
같은 멱등 키로 다른 입력을 보냄 |
| 409 | IDEMPOTENCY_REQUEST_IN_PROGRESS |
같은 멱등 키 요청이 아직 처리 중. Retry-After 후 재시도 |
| 401 | USER_SESSION_INVALID |
use_auto_login + response_type=url 인데 이 쇼핑몰 회원의 유효한 JWT 가 없음(user_id 로만 지정한 경우 포함) |
| 404 | USER_NOT_FOUND |
user_id 가 이 쇼핑몰 회원이 아님(없음·탈퇴·다른 쇼핑몰) |
| 403 | USER_NOT_MATCH |
JWT 와 user_id 가 다른 회원 |
| 400 | API_PARAM_INVALID |
client_key 만으로 부르며 user_id 를 보냄(payload.reason: "merchant_auth_required") |
| 400 | ORDER_PRICE_NOT_MATCH |
(호환 방식) price 가 서버 계산 금액과 다름. payload.price(요청 값)·payload.total_price(서버 계산 값) |
| 400 | ORDER_PRICE_LT_ZERO |
price 가 0 미만 |
| 400 | ORDER_PRODUCT_BLANK |
상품이 없음 |
| 404 | ORDER_PRODUCT_NOT_FOUND |
이 쇼핑몰에 없는 상품 |
| 404 | ORDER_OPTION_NOT_FOUND |
없거나 이 상품의 옵션이 아님 |
| 400 | ORDER_PRODUCT_NEED_OPTION |
옵션 필수 상품에 옵션이 없음 |
| 400 | ORDER_PRODUCT_STOCK_OUT / ORDER_OPTION_STOCK_OUT |
재고 부족 |
| 400 | ORDER_SUBSCRIPTION_ONLY |
구독 상품과 일반 상품을 함께 주문 |
| 403 | PROJECT_GUEST_CHECKOUT_DISABLED |
비회원 주문을 막아 둔 쇼핑몰에 비회원으로 요청 |
| 400 | ORDER_GUEST_SUBSCRIPTION_NOT_ALLOWED |
비회원이 구독 상품을 주문 |
| 400 | USER_CORPORATE_TYPE_INVALID |
회원 주문인데 uct 가 1·2·3 이 아님 |
| 400 | USER_CORPORATE_TYPE_NOT_ALLOW / USER_INDIVIDUAL_TYPE_NOT_ALLOW |
쇼핑몰이 허용하지 않는 회원 유형으로 주문 |
| 400 | USER_GROUP_NOT_FOUND_CORPORATE / USER_GROUP_NOT_FOUND_CORPORATE_DEPARTMENT |
기업·부서 주문인데 회원에게 기업·부서 정보가 없음 |
| 400 | USER_STAND_BY_PENDING_APPROVAL |
기업 가입 승인 대기 중인 회원 |
| 404 | INVOICE_NOT_FOUND |
없는 invoice_id 또는 다른 프로젝트의 청구서. 주문서를 만들기 전에 확인하므로 주문서는 생기지 않습니다 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-14 견적 토큰(
quote_token) 방식, 구매자 범위 멱등 키, 비회원 결과 조회 토큰(result_token) 추가 - 2026-09-23 문서 최초 작성
- 2026-09-28 견적의
cart_item_id로 결제 완료 시 회원 장바구니 줄에서 결제 수량만큼 차감 - 2026-09-28 JWT 대신
user_id(secretKey 인증)로 회원 주문 지정 - 2026-09-28
invoice_id는 인증된 프로젝트의 청구서만 받고, 주문서 저장 전에 확인(이전: 다른 프로젝트 청구서 회원 정보가 복사됐고, 없는 청구서는 주문서가 저장된 뒤 404)
GET /v1/orders/month
한 회원 그룹(개인·기업·부서)의 한 달 치 결제 내역을 구독·일회성 주문으로 나눠 돌려줍니다. 해당 월에 생성된 결제 완료 주문과, 그룹 통합결제 구독을 모읍니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:order_month - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| query | search_date | string | O | 조회 월 YYYY-MM |
|
| query | user_group_id | string | O | 회원 그룹 ID |
응답
200 OK
{
"summary": {
"search_date": "2026-09",
"billing_period": { "start_date": "2026-09-01", "end_date": "2026-09-30" },
"subscription_summary": {
"active": { "total_amount": 99000, "price": 90000, "tax_free_price": 0, "order_count": 1, "subscription_count": 1 },
"new": { "total_amount": 0, "price": 0, "tax_free_price": 0, "order_count": 0, "subscription_count": 0 }
},
"one_time_summary": { "total_amount": 32000, "price": 29091, "tax_free_price": 0, "order_count": 1 }
},
"subscriptions": [
{
"subscription_id": "66f1...",
"subscription_name": "월간 정기배송",
"subscription_type": "active",
"billing_period": { "start_date": "2026-09-01", "end_date": "2026-09-30" },
"orders": [],
"summary": { "total_amount": 99000, "price": 90000, "tax_free_price": 0, "order_count": 1 }
}
],
"one_time_orders": []
}json| 필드 | 타입 | 설명 |
|---|---|---|
| summary.subscription_summary.active / new | object | 이용 중인 구독 / 이번 달 새로 신청한 구독의 합계 |
| summary.one_time_summary | object | 일회성 주문 합계 |
| subscriptions[] | array | 구독별 묶음. subscription_type 은 active(이용 중) 또는 new(신규 신청) |
| subscriptions[].orders[], one_time_orders[] | array | 주문 항목 (아래 표) |
주문 항목
| 필드 | 타입 | 설명 |
|---|---|---|
| order_id | string | 주문 ID. 그룹 통합결제 구독은 구독 ID |
| order_number | string | 주문번호 |
| created_at | string | 생성 시각 YYYY-MM-DD HH:MM:SS |
| status / payment_status | string | 주문 상태 / 결제 상태의 한글 표시 문구 |
| price.total / price.price / price.tax_free_price | number | 합계 / 공급가 / 면세 금액 |
| receipts[] | array | 결제 영수증. receipt_id, payment_method, status, amount, receipt_url, created_at, 결제수단별 데이터(card_data 등) |
| products | array | 주문 상품 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | MONTHLY_BILLING_SEARCH_DATE_BLANK |
search_date 없음 |
| 400 | MONTHLY_BILLING_SEARCH_DATE_FORMAT_INVALID |
YYYY-MM 형식이 아님 |
| 400 | MONTHLY_BILLING_SEARCH_DATE_INVALID |
존재하지 않는 월(예: 2026-13) |
| 400 | MONTHLY_BILLING_USER_GROUP_ID_BLANK |
user_group_id 없음 |
| 400 | MONTHLY_BILLING_USER_GROUP_ID_INVALID |
ID 형식이 아님 |
| 404 | MONTHLY_BILLING_USER_GROUP_NOT_FOUND |
없는 회원 그룹 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-23 문서 최초 작성
GET /v1/orders/:id/purchases
주문의 발주(배송 단위) 목록 — 운송장·택배사·발주 상태·배송 추적 이력을 돌려줍니다. 주문 상세의 order_purchases 와 같은 값이며, 배송 정보만 필요할 때 씁니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:order_detail - 회원: JWT 또는 user_id 선택 —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정) — 회원 JWT. 구매자 화면에 쓸 때 보내면 그 회원의 주문만 돌려줍니다(다른 회원·비회원 주문은 404). 보내지 않으면 쇼핑몰의 어느 주문이든 조회합니다.
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 주문번호 |
응답
200 OK — 발주 배열. 결제 전 주문이거나 배송이 없는 주문이면 빈 배열입니다.
[
{
"order_purchase_id": "66f1...",
"order_purchase_number": "OP2409230001",
"order_id": "66f1...",
"status": 4,
"delivery_type": 1,
"delivery_company_code": "cjgls",
"tracking_number": "123456789012",
"amount_delivery_fee": 3000,
"sent_at": "2026-09-23T15:00:00+09:00",
"delivered_at": null,
"order_purchase_products": [
{ "chosen_product_option_id": "66f1...", "product_id": "66f0...", "product_name": "기본 티셔츠", "quantity": 1, "status": 4 }
],
"last_synced_at": "2026-09-23T16:00:00+09:00",
"tracking_histories": [],
"delivery_delay": null
}
]json| 필드 | 타입 | 설명 |
|---|---|---|
| order_purchase_id | string | 발주 ID |
| order_purchase_number | string | 발주번호. 발송 처리(PUT)에 씁니다 |
| status | integer | 발주 상태. 0 결제 전, 1 발주 대기, 2 발주 확인, 3 상품 준비중, 4 발송 완료, 5 배송 완료, -1 발주 취소, -2 발주 오류, -3 발주 무효 |
| delivery_type | integer | 배송 방식. 1 택배, 2 직접 배송, 3 퀵, 4 방문 수령 |
| delivery_company_code | string | 택배사 코드 |
| tracking_number | string | 운송장 번호 |
| amount_delivery_fee | number | 이 발주의 배송비. delivery_fee_policy 가 착불이면 0 이어도 무료가 아닙니다 |
| order_confirmed_at, prepared_at, sent_at, delivered_at | string | 상태별 처리 시각 |
| order_purchase_products[] | array | 발주에 담긴 품목. chosen_product_option_id 로 품목 단위 발송 처리를 합니다 |
| last_synced_at | string | 배송 추적을 마지막으로 동기화한 시각 |
| tracking_histories[] | array | 배송 추적 상태 이력(최신 순) |
| delivery_delay | object | 배송 지연 안내 중이면 지연 정보, 아니면 null |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | ORDER_NOT_FOUND |
없는 주문번호. 회원을 지정했으면 다른 회원·비회원 주문도 404 |
| 401 | ORDER_DENIED |
다른 쇼핑몰의 주문 |
| 404 | USER_NOT_FOUND |
user_id 가 이 쇼핑몰 회원이 아님 |
| 403 | USER_NOT_MATCH |
JWT 와 user_id 가 다른 회원 |
| 401 | USER_SESSION_INVALID / USER_JWT_INVALID |
JWT 를 보냈지만 무효 — 회원 JWT |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-03 추가
- 2026-09-23 문서 최초 작성
- 2026-09-28 JWT 또는
user_id로 회원을 지정하면 그 회원의 주문만 조회
PUT /v1/orders/:id/purchases
발송 처리 — 주문의 발주 상태·운송장을 바꿉니다. 관리자의 [발송처리]와 같은 규칙을 탑니다. 발송 완료로 바꾸면서 운송장을 넣으면 배송 추적을 시작합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:order_purchase_update - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 주문번호 | |
| body | purchases | array | O | 바꿀 발주 목록. 1~50개 |
purchases[] 항목
| 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| order_purchase_number | string | O | 이 주문에 속한 발주번호 |
| status | integer | O | 2 발주 확인, 3 상품 준비중, 4 발송 완료, 5 배송 완료 중 하나. 취소·무효는 관리자에서만 할 수 있습니다 |
| chosen_product_option_id | string | 넣으면 그 품목만 바꿉니다. 없으면 발주 전체와 모든 품목을 바꿉니다 | |
| delivery_type | integer | 배송 방식 (1 택배, 2 직접 배송, 3 퀵, 4 방문 수령) |
|
| delivery_company_code | string | 택배사 코드 | |
| tracking_number | string | 운송장 번호. 빈 문자열을 보내면 지웁니다 |
{
"purchases": [
{ "order_purchase_number": "OP2409230001", "status": 4, "delivery_company_code": "cjgls", "tracking_number": "123456789012" }
]
}json항목은 순서대로 처리합니다. 요청 형식 검사(개수·발주번호·상태 값)는 처리 전에 모두 끝나지만, 처리 도중 한 항목이 거절되면(예: 취소된 발주) 앞 항목의 변경은 그대로 남습니다. 오류를 받으면 발주 조회로 현재 상태를 확인하세요.
응답
200 OK — 변경 후의 발주 배열. 발주 조회와 같은 형식입니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | ORDER_NOT_FOUND |
없는 주문번호 |
| 401 | ORDER_DENIED |
다른 쇼핑몰의 주문 |
| 400 | REQUIRED_PARAMETER_IS_MISSING |
purchases 가 없음 |
| 400 | INVALID_PARAMETER |
purchases 가 배열이 아님, 50개 초과, 허용되지 않는 status |
| 404 | ORDER_PURCHASE_NOT_FOUND |
이 주문에 없는 발주번호 |
| 404 | ORDER_PRODUCT_NOT_FOUND |
chosen_product_option_id 가 그 발주의 품목이 아님 |
| 400 | ORDER_PURCHASE_NOT_PERMIT |
취소·무효·오류로 끝난 발주, 또는 결제가 전액 취소된 주문의 미발송 발주를 다시 진행하려 함 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-03 추가
- 2026-09-23 문서 최초 작성
GET /v1/orders/:id/result
구매자용 결제 결과 — 외부 결제 페이지에서 돌아온 구매자가 자기 주문의 결제·배송 상태만 확인합니다. 결제 성공 여부는 리다이렉트 쿼리가 아니라 서버가 영수증 검증·웹훅으로 저장한 상태로만 판정하므로, 결과 화면은 이 값을 기준으로 그리세요. 조회만 하며 여러 번 호출해도 상태가 바뀌지 않습니다.
가맹점 서버가 주문 전체를 볼 때는 주문 상세를 씁니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:order_result_customer - 구매자 확인은 둘 중 하나로 합니다.
- 회원: JWT 또는 user_id —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정) — 회원 JWT. JWT 는 보내면 유효해야 하며, 그 회원의 주문만 봅니다. - 비회원:
Bootpay-Order-Result-Token헤더에 결제 준비 응답의result_token, 그리고 결제 준비 때와 같은Bootpay-Device-UUID. 주문번호나 기기 UUID 만으로는 조회할 수 없습니다.
- 회원: JWT 또는 user_id —
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 주문번호 | |
| header | Bootpay-Order-Result-Token | string | 비회원이면 O | 결제 준비에서 받은 결과 조회 토큰(24시간 유효) | |
| header | Bootpay-Device-UUID | string | 비회원이면 O | 결제 준비 때 보낸 값과 같아야 함 |
응답
200 OK — payment_status 가 pending 이면 다시 조회할 간격(초)을 Retry-After 헤더로 줍니다(가상계좌 입금 대기 60, 그 외 3).
{
"order_number": "2409231234567",
"payment_status": "paid",
"fulfillment_status": "preparing",
"amounts": {
"currency": "KRW",
"product_price": 29000,
"delivery_price": 3000,
"total_price": 32000,
"paid_price": 32000,
"refunded_price": 0
},
"items": [
{ "product_id": "66f0...", "product_option_id": "66f0...", "name": "기본 티셔츠 블랙-L", "quantity": 1 }
],
"updated_at": "2026-09-23T03:01:12Z"
}json| 필드 | 타입 | 설명 |
|---|---|---|
| order_number | string | 주문번호 |
| payment_status | string | pending(결제 진행·입금 대기), paid, partially_refunded, refunded, failed, cancelled(결제 없이 닫힘·결제 전 취소) |
| fulfillment_status | string | 결제가 확정된 주문만 의미 있음. not_started(결제 미확정), not_required(배송 없는 상품), unfulfilled, preparing, shipping, delivered, failed, on_hold, cancel_requested, cancelled, returning, returned, exchanging, exchanged |
| amounts.paid_price / refunded_price | number | 결제 확정 전에는 0 |
| items[] | array | 주문 시점의 상품명(옵션 포함)·수량. 가격은 싣지 않습니다 |
| updated_at | string | 주문 마지막 변경 시각(UTC) |
구매자 개인정보·영수증 원문·결제수단 정보는 싣지 않습니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | ORDER_NOT_FOUND |
없는 주문, 다른 회원·다른 쇼핑몰의 주문 (구분하지 않습니다) |
| 401 | ORDER_RESULT_TOKEN_INVALID |
(비회원) 토큰 없음·위조, 다른 주문·다른 기기의 토큰 |
| 410 | ORDER_RESULT_TOKEN_EXPIRED |
(비회원) 토큰 만료. 비회원 주문 조회를 안내하세요 |
| 401 | USER_SESSION_INVALID / USER_JWT_INVALID |
(회원) JWT 를 보냈지만 무효 — 회원 JWT |
| 404 | USER_NOT_FOUND |
(회원) user_id 가 이 쇼핑몰 회원이 아님 |
| 403 | USER_NOT_MATCH |
(회원) JWT 와 user_id 가 다른 회원 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-14 추가
- 2026-09-23 문서 최초 작성
- 2026-09-28 JWT 대신
user_id로 회원 지정
GET /v1/orders
주문 목록. 최신 주문부터 돌려줍니다.
- 회원을 지정하지 않으면 가맹점 서버 조회입니다. 쇼핑몰의 모든 주문을 조건으로 찾습니다.
Bootpay-User-JWT또는user_id로 회원을 지정하면 구매자 조회입니다. 그 회원의 주문만 봅니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:order_list - 회원: JWT 또는 user_id 선택 —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정) — 회원 JWT. JWT 는 보내면 유효해야 합니다(무효면 401).user_id는 secretKey 인증에서만 받습니다(client_key만이면 400).
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| query | search_date_from | string | 오늘 00:00 | 조회 시작 시각. 별칭 css_at |
|
| query | search_date_to | string | 오늘 23:59:59 | 조회 끝 시각. 날짜만 주면 그날 끝까지. 별칭 cse_at |
|
| query | cs_type | string | c_at |
기간 기준. c_at 주문 생성 시각, p_at 결제 시각 |
|
| query | status | string, array | 주문 상태. enum 문자열 또는 숫자, 여러 개는 콤마 또는 status[]=a&status[]=b. 별칭 s |
||
| query | payment_status | string, array | 결제 상태 묶음. receipt_ready(결제 전·진행 중), receipt_success(결제 성공), receipt_fail(실패·만료), receipt_cancelled(취소) 중에서. 별칭 s_p |
||
| query | keyword | string | 주문번호·주문명·구매자 정보 검색 | ||
| query | user_id | string | 회원 ID(_id) 또는 가맹점 회원 ID(ex_uid). 이 쇼핑몰 회원이 아니면 404. JWT 와 함께 보내면 같은 회원이어야 함 |
||
| query | user_group_id | string | 회원 그룹 ID | ||
| query | order_subscription_ids | string, array | 구독 ID. 콤마 문자열 또는 배열 | ||
| query | subscription_billing_type | integer | 구독 결제 유형 | ||
| query | page | integer | 1 | 1 이상 | |
| query | limit | integer | 20 | 1~50. 범위를 벗어나면 가까운 경계값으로 조회합니다 |
기간을 주지 않으면 오늘 하루만 조회합니다. 전체를 보려면 기간을 넉넉히 지정하세요. 이 API 는 공통 페이지네이션과 달리 limit 최대값이 50 이고, page 는 1 이상으로 보내야 합니다.
해석할 수 없는 status·payment_status 값은 무시하지 않고 400 INVALID_PARAMETER 로 거절합니다.
응답
200 OK
{
"list": [
{
"order_id": "66f1...",
"order_number": "2409231234567",
"order_name": "기본 티셔츠 외 1건",
"status": "payment_completed",
"receipt_status": "receipt_success",
"price": 32000,
"product_price": 29000,
"amount_delivery_fee": 3000,
"purchased_at": "2026-09-23T12:01:10+09:00",
"created_at": "2026-09-23T12:00:00+09:00",
"products": [ { "product_id": "65b2...", "quantity": 1 } ],
"user": {},
"user_address": { "zipcode": "06236" },
"receipt_data": { "card_data": {} }
}
],
"count": 1
}json| 필드 | 타입 | 설명 |
|---|---|---|
| list[] | array | 주문 목록 |
| count | integer | 조건에 맞는 전체 주문 수 |
list[] 주요 필드
| 필드 | 타입 | 설명 |
|---|---|---|
| order_id, order_number, order_name | string | 주문 ID·주문번호·주문명 |
| status, receipt_status | string | 주문 상태, 결제 영수증 상태 |
| origin_price, product_price, price, tax_free_price | number | 정가 합계, 상품 금액, 결제 금액, 면세 금액 |
| cancelled_price, cancelled_tax_free_price | number | 취소된 금액 |
| amount_delivery_fee | number | 배송비. 착불 상품이면 0 이어도 무료가 아닙니다 |
| use_delivery, delivery_type | boolean, string | 배송 여부, 배송 방식(parcel, direct, quick, pickup) |
| purchased_at, created_at, payment_expires_at | string | 결제·생성 시각, 결제 기한 |
| products[] | array | 주문 상품. 주문 상세의 products[] 와 같은 형식입니다(썸네일·상품명을 위해 상세를 다시 부를 필요가 없습니다) |
| user, user_address | object | 구매자, 배송지 |
| receipt_data | object | 결제수단별 결제 정보(card_data, bank_data, vbank_data 등) |
| issued_data | object | 가상계좌 발급 정보 |
| order_subscriptions | array | 구독 주문이면 구독 정보 |
| is_shipping_ready, is_delivery_delayed | boolean | 배송 준비 전환 여부, 배송 지연 안내 여부 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | INVALID_PARAMETER |
해석할 수 없는 status·payment_status |
| 401 | USER_SESSION_INVALID / USER_JWT_INVALID |
JWT 를 보냈지만 무효 — 회원 JWT |
| 404 | USER_NOT_FOUND |
user_id 가 이 쇼핑몰 회원이 아님(없음·탈퇴·다른 쇼핑몰) |
| 403 | USER_NOT_MATCH |
JWT 와 user_id 가 다른 회원 |
| 400 | API_PARAM_INVALID |
client_key 만으로 부르며 user_id 를 보냄(payload.reason: "merchant_auth_required") |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-08-14
limit파라미터 지원(1~50) - 2026-08-27
status·payment_status에 enum 문자열 허용 - 2026-09-14
Bootpay-User-JWT를 보내면 그 회원의 주문만 조회 - 2026-09-28
products[]·user_address가 항상 비어 있던 결함 수정 - 2026-09-28
user_id가 필터에서 회원 지정으로 바뀜 — 없는 회원이면 전체 목록 대신 404 - 2026-09-23 문서 최초 작성
GET /v1/orders/:id
주문 상세. 결제·구매자·상품·영수증과 발주(배송) 정보를 함께 돌려줍니다.
- 회원을 지정하지 않으면 가맹점 서버 조회입니다. 수시결제 주문이면 재결제용
charge_key도 이 경우에만 실립니다. Bootpay-User-JWT또는user_id로 회원을 지정하면 구매자 조회입니다. 그 회원의 주문이 아니면 404 이고,charge_key는 싣지 않습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:order_detail - 회원: JWT 또는 user_id 선택 —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정) — 회원 JWT. JWT 는 보내면 유효해야 합니다(무효면 401).user_id는 secretKey 인증에서만 받습니다(client_key만이면 400).
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 주문번호 | |
| query | user_id | string | 구매자 조회 회원 ID(_id 또는 ex_uid) |
응답
200 OK — 값이 없는 필드는 응답에서 빠집니다.
{
"order_number": "2409231234567",
"order_name": "기본 티셔츠 외 1건",
"status": "payment_completed",
"receipt_status": "receipt_success",
"price": 32000,
"tax_free_price": 0,
"cancelled_price": 0,
"unit": "KRW",
"type": "shop",
"order_request_type": "item",
"receipt_id": "66f1...",
"purchased_at": "2026-09-23T12:01:10+09:00",
"created_at": "2026-09-23T12:00:00+09:00",
"products": [],
"user": {},
"receipt_success_data": {},
"order_url": "https://...",
"order_purchases": []
}json| 필드 | 타입 | 설명 |
|---|---|---|
| order_number, order_name | string | 주문번호, 주문명 |
| status, receipt_status | string | 주문 상태, 결제 영수증 상태 |
| type | string | shop(회원 쇼핑몰 주문), invoice(비회원·청구서 주문) |
| order_request_type | string | item 일반, subscription 구독, subscription_requested 구독 신청 |
| price, tax_free_price | number | 결제 금액, 면세 금액 |
| cancelled_price, cancelled_tax_free_price | number | 취소된 금액 |
| reserved_cancel_price, reserved_cancel_tax_free_price | number | 취소 예정 금액 |
| unit | string | 통화 (KRW 등) |
| invoice_id, request_id, metadata | 청구서 ID, 가맹점 요청 ID, 가맹점 메타데이터 | |
| receipt_id | string | 결제 영수증 ID |
| username, user_phone, user_email, user_address | 주문자 정보 | |
| purchased_at, created_at | string | 결제·생성 시각 |
| products[] | array | 주문 상품 |
| user | object | 회원 정보 |
| order_subscriptions, order_subscription_bills | array | 구독 주문이면 구독·청구 정보 |
| receipt_success_data, issued_data, receipt_cancelled_data | object | 결제 성공·가상계좌 발급·취소 영수증 데이터 |
| auto_charge_key_issued | boolean | 수시결제 재결제 키 발급 여부 |
| charge_key | string | 수시결제 재결제 키. 가맹점 서버 조회에서만 옵니다. 서버에만 보관하세요 |
| order_url | string | 결제 페이지 주소 |
| order_purchases[] | array | 발주(배송) 목록 — 발주 조회와 같은 형식 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | ORDER_NOT_FOUND |
없는 주문번호. 구매자 조회에서는 다른 회원·다른 쇼핑몰 주문도 404 |
| 401 | ORDER_DENIED |
(가맹점 서버 조회) 다른 쇼핑몰의 주문 |
| 401 | USER_SESSION_INVALID / USER_JWT_INVALID |
JWT 를 보냈지만 무효 — 회원 JWT |
| 404 | USER_NOT_FOUND |
user_id 가 이 쇼핑몰 회원이 아님 |
| 403 | USER_NOT_MATCH |
JWT 와 user_id 가 다른 회원 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-03
order_purchases추가 - 2026-09-14
Bootpay-User-JWT를 보내면 그 회원의 주문만 조회 - 2026-09-23 문서 최초 작성
- 2026-09-28
user_id로도 구매자 조회(그 회원 주문만,charge_key없음)
