주문

결제 준비(주문서 생성), 주문 목록·상세 조회, 발주(배송) 처리, 구매자용 결제 결과 조회를 다룹니다. 주문 취소·구매확정·결과 페이지용 조회는 주문 처리를 봅니다.

  • 경로의 :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 입니다.
  • 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"
}json

response_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 만으로는 조회할 수 없습니다.

요청

위치 이름 타입 필수 기본값 설명
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 없음)

함께 보기