주문 처리 (취소·구매확정·결과)

결제가 끝난 주문을 가맹점 서버에서 처리하는 API 입니다. 결제 취소 요청과 그 승인·반려·철회, 분리 승인 주문의 승인(구매확정), 결제 결과 조회, 구독 결제 건 취소를 다룹니다.

모든 API 는 Basic 인증으로 호출하며, 인증한 프로젝트의 주문만 처리합니다. 취소 요청·조회·철회와 결과 조회, 구독 결제 건 취소는 JWT 또는 user_id 로 회원을 지정할 수 있습니다(선택) — 지정하면 그 회원의 주문만 다룹니다. 승인·반려·구매확정은 판매자 행위라 회원을 받지 않습니다.

구매자 화면(마이페이지 취소 등)에서 쓸 때 — 이 API 는 secret key 로 인증하는 가맹점 권한이라 주문번호만 맞으면 이 몰의 어떤 주문이든 처리합니다. 브라우저에서 직접 부르지 말고 브라우저 → 쇼핑몰 서버(Next.js·Nuxt 서버 등) → Bootpay commerce 로 호출하세요. 쇼핑몰 서버는 로그인한 회원을 user_id(또는 그 회원의 Bootpay-User-JWT)로 함께 보내세요. 그러면 Commerce 가 그 회원의 주문인지 확인하고(아니면 404), 즉시취소 여부·요청자 같은 옵션을 구매자 규칙으로 정합니다. 회원을 보내지 않으면 가맹점 요청으로 보고 요청 옵션을 그대로 씁니다. 구매자 화면에서 본인 주문의 결과를 보여 줄 때는 GET /v1/orders/:id/result를 씁니다.

취소 요청의 흐름

  1. POST /v1/order/cancel 로 취소 요청을 만듭니다. 요청 상태는 cancel_requested 입니다. cancel_immediately=true 면 승인 없이 바로 결제를 취소합니다.
  2. 판매자가 PUT /v1/order/cancel/:id/approve 로 승인하면 결제가 취소되고(cancel_approved), reject 로 반려하면 cancel_rejected 가 됩니다.
  3. 구매자가 요청을 거둬들이면 withdraw(또는 DELETE)로 철회합니다(cancel_withdrawn).

취소 요청 응답의 status 값:

값 뜻
cancel_calculated 금액만 계산됨(요청 전)
cancel_requested 취소 요청됨, 승인 대기
cancel_approved 승인되어 결제 취소 완료
cancel_approval_failed 승인 중 결제 취소 실패. 다시 승인할 수 있습니다
cancel_approval_critical_failed 승인 중 예상하지 못한 오류
cancel_rejected 반려됨
cancel_withdrawn 철회됨

취소 요청 응답 형식

취소 요청을 만들거나 승인·반려·철회한 응답은 주문 전체 정보​​에 order_cancellation_request_history 를 더한 형태입니다.

{
  "order_number": "2609231234567890",
  "order_name": "기본 티셔츠 외 1건",
  "price": 30000,
  "cancelled_price": 0,
  "status": 2,
  "receipt_status": 1,
  "products": [],
  "user": {},
  "order_cancellation_request_history": {
    "order_cancellation_request_history_id": "66f0c1...",
    "order_cancellation_request_id": "66f0c1...",
    "cancel_id": "c-20260923-0001",
    "cancel_request_type": 3,
    "cancel_price": 15000,
    "cancel_tax_free_price": 0,
    "final_refund_amount": 15000,
    "cancel_requester": "구매자",
    "cancel_message": "단순 변심",
    "cancel_immediately": false,
    "status": "cancel_requested",
    "created_at": "2026-09-23T10:00:00+09:00",
    "cancel_products": [
      {
        "product_id": "66a1...",
        "product_option_id": "66a2...",
        "cancel_quantity": 1,
        "cancel_price": 15000,
        "cancel_tax_free_price": 0
      }
    ]
  }
}json

주문 쪽 필드는 주문 상세와 같은 결제 응답 형식입니다(order_number·order_name·price·tax_free_price·cancelled_price·cancelled_tax_free_price·reserved_cancel_price·reserved_cancel_tax_free_price·status·receipt_status·receipt_id·purchased_at·products·user·order_url 등).

order_cancellation_request_history 필드:

필드 타입 설명
order_cancellation_request_history_id string 취소 요청 ID. 승인·반려·철회의 :id 로 씁니다
order_cancellation_request_id string 위와 같은 값
cancel_id string 취소 요청 식별자(요청에 보낸 값, 없으면 서버가 만든 UUID)
order_request_type integer 주문 종류
cancel_request_type integer 2 금액 취소, 3 상품 단위 취소, 구독 회차 취소는 그 외 값
cancel_price number 취소(환불)할 금액
cancel_tax_free_price number 취소할 면세 금액
final_refund_amount number 최종 환불액
cancel_before_price / cancel_after_price number 취소 직전·직후 결제 금액 (처리 후 채워짐)
cancel_before_tax_free_price / cancel_after_tax_free_price number 취소 직전·직후 면세 금액
cancel_requester string 요청자 이름
cancel_message string 취소 사유
cancel_reason_key string 취소 사유 키 (보낸 경우)
cancel_immediately boolean 즉시 취소 요청 여부
is_partial_cancelled boolean 부분 취소 여부
status string 위 상태 표
cancel_result_type integer 0 정상, 1 결제가 이미 취소되어 있어 주문 상태만 바꿈, 2 결제 취소 실패 후 주문만 취소 처리
action_at string 승인·반려 시각 (ISO 8601)
action_message string 승인·반려 메시지
withdrawn_at string 철회 시각
completed_at string 처리 완료 시각
created_at string 요청 시각
cancel_products array 상품 단위 취소 내역 (product_id·product_option_id·cancel_quantity·cancel_price·cancel_tax_free_price)
cancel_order_subscription_bills array 구독 회차 취소 내역 (order_subscription_bill_id·cancel_price·cancel_tax_free_price·cancel_quantity)
point_restoration_amount number 돌려줄 적립금 합계 (상품 단위 취소일 때)
coupon_deduction_amount number 환불에서 빠지는 쿠폰 할인 합계 (상품 단위 취소일 때)

값이 없는 필드는 응답에서 빠집니다.

GET /v1/order/cancel

주문 하나의 취소 요청 내역을 최신순으로 조회합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_cancel_request_history_list
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT. 지정하면 그 회원의 주문 내역만 봅니다(다른 회원·비회원 주문은 404).

요청

위치 이름 타입 필수 기본값 설명
query order_number string 둘 중 하나 주문번호
query order_id string 둘 중 하나 주문 ID(_id). order_number 가 있으면 order_number 를 씁니다
query user_id string 회원 지정(선택)

둘 다 빼면 404 입니다. 페이지 파라미터는 받지 않습니다. 항상 최신 20건까지 돌려주고, 전체 개수는 count 로 알려 줍니다.

응답

200 OK

{
  "list": [
    {
      "order_cancellation_request_history_id": "66f0c1...",
      "order_cancellation_request_id": "66f0c1...",
      "cancel_id": "c-20260923-0001",
      "cancel_price": 15000,
      "status": "cancel_requested",
      "created_at": "2026-09-23T10:00:00+09:00"
    }
  ],
  "count": 1
}json

list 항목은 위 취소 요청 응답 형식의 order_cancellation_request_history 와 같은 필드에, 처리된 요청이면 rollback_info(배송비 조정·적립금 복원·쿠폰 복원 내역)가 더해집니다. 주문 정보는 들어 있지 않습니다.

오류

HTTP error_code 언제
404 ORDER_NOT_FOUND 이 프로젝트에 없는 주문번호·주문 ID(형식이 틀린 ID 포함). 회원을 지정했으면 다른 회원·비회원 주문도 404
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-23 문서 최초 작성
  • 2026-09-28 order_id 로 조회되지 않던(항상 404, 형식이 틀리면 500) 결함 수정, 주문을 빼면 404, JWT 또는 user_id 로 회원 지정

POST /v1/order/cancel

결제 완료된 주문에 취소 요청을 만듭니다. 금액 취소, 상품 단위 취소, 구독 회차 취소를 지원하며, cancel_immediately=true 면 승인 단계 없이 바로 결제를 취소합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_cancel
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT. 구매자 요청이면 보내세요(위 안내).
    • 지정하면 그 회원의 주문만 취소 요청할 수 있습니다(다른 회원·비회원 주문은 404, 이력도 만들지 않음).
    • 지정하면 구매자 규칙​​으로 처리합니다. request_cancel_parameters 중 cancel_id·cancel_price·cancel_tax_free_price·cancel_products·cancel_order_subscription_bills·cancel_message 만 쓰고, 나머지(cancel_immediately·force·cancel_requester·reason_key·귀책·판매자 수동 조정)는 무시합니다. 요청자는 구매자 로 저장됩니다.
    • 즉시 취소 여부는 서버가 정합니다. 배송 준비 전환 전(결제 직후 유예 구간)이면 승인 없이 바로 취소하고, 그 밖에는 승인 대기(cancel_requested)입니다.

요청

위치 이름 타입 필수 기본값 설명
body order_number string O 주문번호
body request_cancel_parameters object {} 취소 내용. 아래 표
body user_id string 구매자 요청의 회원(선택). 지정하면 구매자 규칙(위 인증)

request_cancel_parameters:

이름 타입 필수 기본값 설명
cancel_id string 서버가 만든 UUID 가맹점이 정하는 취소 요청 식별자. 같은 주문에 이미 쓴 값이면 거절합니다. 재시도해도 두 번 취소되지 않게 하려면 직접 정해 보내세요
cancel_products array 상품 단위 취소. 항목마다 product_id(필수), product_option_id, chosen_product_option_id, cancel_quantity(1 이상)
cancel_order_subscription_bills array 구독 주문의 회차 취소. 항목마다 order_subscription_bill_id, cancel_quantity(1 이상)
cancel_price number 남은 취소 가능 금액 전부 금액 취소 금액. cancel_products 없이 0 이거나 생략하면 남은 금액 전체​​를 취소합니다
cancel_tax_free_price number 남은 면세 금액 전부 금액 취소의 면세 금액
cancel_requester string 관리자 요청자 이름
cancel_message string 요청취소 취소 사유
reason_key string 취소 사유 키. 상품 단위 취소의 환불액 계산에 반영됩니다
cancel_immediately boolean false true 면 승인 없이 바로 결제를 취소합니다
  • 상품 단위 취소는 환불액을 서버가 계산합니다(적립금·쿠폰 배분 반영). 응답의 cancel_price·final_refund_amount 가 실제 환불액입니다.
  • 이미 금액 취소가 진행된 주문은 상품 단위 취소를 할 수 없습니다.
  • 배송중 상태의 주문은 요청을 만들기 전에 배송 전 상태로 되돌리고, 아직 발송하지 않은 발주는 무효 처리합니다.
{
  "order_number": "2609231234567890",
  "request_cancel_parameters": {
    "cancel_id": "c-20260923-0001",
    "cancel_products": [
      { "product_id": "66a1...", "product_option_id": "66a2...", "cancel_quantity": 1 }
    ],
    "cancel_requester": "구매자",
    "cancel_message": "단순 변심"
  }
}json

응답

200 OK — 취소 요청 응답 형식. 즉시 취소가 끝났는데 결제가 이미 취소돼 있었던 경우처럼 결과가 정상과 다르면 cancel_result_type·cancel_result_message 와 결제 취소 결과 필드가 최상위에 더해집니다.

오류

HTTP error_code 언제
404 ORDER_NOT_FOUND 이 프로젝트에 없는 주문번호. 회원을 지정했으면 다른 회원·비회원 주문도 404
404 USER_NOT_FOUND user_id 가 이 쇼핑몰 회원이 아님
403 USER_NOT_MATCH JWT 와 user_id 가 다른 회원
401 USER_SESSION_INVALID / USER_JWT_INVALID JWT 를 보냈지만 무효 — 회원 JWT
404 ORDER_NOT_SUCCESS 결제 완료 상태가 아닌 주문
400 ORDER_CANCEL_ID_ALREADY_REQUESTED 이 주문에 이미 쓴 cancel_id
400 ORDER_PROGRESS_CANCEL_UNABLE 지금 진행 상태에서는 취소할 수 없음
400 ORDER_CANCEL_IMMEDIATELY_UNABLE 즉시 취소를 할 수 없는 상태
400 ORDER_PRODUCT_CANCEL_UNABLE 금액 취소가 진행된 주문에 상품 단위 취소
400 ORDER_CANCEL_PRODUCT_OPTION_NOT_FOUND cancel_products 의 상품·옵션이 주문에 없음
400 ORDER_CANCEL_QTY_INVALID 취소 수량이 1 미만이거나 취소 가능 수량 초과
404 ORDER_CANCEL_SUBSCRIPTION_BILL_NOT_FOUND 주문에 없는 구독 회차
400 ORDER_CANCEL_SUBSCRIPTION_BILL_QTY_INVALID 회차 취소 수량 초과
400 ORDER_CANCEL_PRICE_LT_ZERO cancel_price 가 음수
400 ORDER_CANCEL_PRICE_OVER 취소 금액이 취소 가능 금액보다 큼
400 ORDER_CANCEL_TAX_FREE_OVER 면세 금액이 취소 가능 면세 금액보다 큼
500 ORDER_CANCEL_CRITICAL_ERROR 즉시 취소 중 예상하지 못한 오류

즉시 취소에서 결제사 취소가 실패하면 결제사 오류가 그대로 옵니다. 공통 오류는 오류를 봅니다.

변경 이력

  • 2026-09-28 구매자 화면에서 쓸 때의 호출 경로(쇼핑몰 서버 경유)·소유 확인 안내 추가
  • 2026-09-28 JWT 또는 user_id 로 회원을 지정하면 소유 확인 + 구매자 규칙(즉시취소·요청자 서버 판정)
  • 2026-09-23 문서 최초 작성

PUT /v1/order/cancel/:id/approve

취소 요청을 승인하고 결제를 취소합니다. 환불액 계산, 재고·적립금·쿠폰 되돌리기, 결제사 취소가 이 호출에서 처리됩니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:order_cancel_request_history_approve. 이 API 는 Bootpay-Role 헤더가 없으면 역할을 supervisor 로 봅니다. 헤더를 보내면 그 역할로 검사합니다(예: Bootpay-Role: user → user:order_cancel_request_history_approve)
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 취소 요청 ID (order_cancellation_request_history_id)
body message string 승인 메시지 (action_message 로 남음)

응답

200 OK — 취소 요청 응답 형식. status 는 cancel_approved 입니다. 결제가 이미 취소돼 있어 주문 상태만 바꾼 경우 등에는 cancel_result_type·cancel_result_message 가 최상위에 더해집니다.

오류

HTTP error_code 언제
404 ORDER_CANCEL_NOT_REQUESTED 이 프로젝트에 없는 요청 ID, 또는 승인 대기(cancel_requested) 상태가 아닌 요청
400 ORDER_CANCEL_NOT_REQUESTED 처리 도중 요청 상태가 바뀜
500 ORDER_CANCEL_CRITICAL_ERROR 예상하지 못한 오류

결제사 취소가 실패하면 결제사 오류가 오고 요청은 cancel_approval_failed 로 남습니다. 원인을 해결한 뒤 다시 승인하세요. 공통 오류는 오류를 봅니다.

변경 이력

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

PUT /v1/order/cancel/:id/reject

취소 요청을 반려합니다. 주문은 요청 직전의 진행 상태로 돌아갑니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:order_cancel_request_history_reject. Bootpay-Role 헤더가 없으면 역할은 supervisor 입니다
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 취소 요청 ID
body message string 반려 사유 (action_message 로 남음)

응답

200 OK — 취소 요청 응답 형식. status 는 cancel_rejected 입니다.

오류

HTTP error_code 언제
404 ORDER_CANCEL_REQUEST_NOT_FOUND 이 프로젝트에 없는 요청 ID
400 ORDER_CANCEL_NOT_REQUESTED 승인 대기 상태가 아닌 요청
400 ORDER_CANCEL_REQUEST_REJECT_UNABLE 주문 쪽 상태 때문에 반려할 수 없음
500 ORDER_CANCEL_REQUEST_REJECT_CRITICAL_ERROR 예상하지 못한 오류

공통 오류는 오류를 봅니다.

변경 이력

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

PUT /v1/order/cancel/:id/withdraw

취소 요청을 철회합니다(구매자가 마음을 바꾼 경우). 주문은 요청 직전의 진행 상태로 돌아갑니다. DELETE /v1/order/cancel/:id 와 같은 동작입니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_cancel_request_history_withdraw
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT. 지정하면 그 회원 주문의 요청만 철회합니다(아니면 404).

요청

위치 이름 타입 필수 기본값 설명
path id string O 취소 요청 ID
query·body user_id string 회원 지정(선택)

응답

200 OK — 취소 요청 응답 형식. status 는 cancel_withdrawn 입니다.

오류

HTTP error_code 언제
404 ORDER_CANCEL_REQUEST_NOT_FOUND 이 프로젝트에 없는 요청 ID. 회원을 지정했으면 다른 회원 주문의 요청도 404
404 USER_NOT_FOUND user_id 가 이 쇼핑몰 회원이 아님
403 USER_NOT_MATCH JWT 와 user_id 가 다른 회원
401 USER_SESSION_INVALID / USER_JWT_INVALID JWT 를 보냈지만 무효 — 회원 JWT
400 ORDER_CANCEL_REQUEST_WITHDRAW_UNABLE 승인 대기 상태가 아니라 철회할 수 없음
500 ORDER_CANCEL_REQUEST_WITHDRAW_CRITICAL_ERROR 예상하지 못한 오류

공통 오류는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성
  • 2026-09-28 JWT 또는 user_id 로 회원을 지정하면 그 회원 주문의 요청만 철회

DELETE /v1/order/cancel/:id

취소 요청을 철회합니다. PUT /v1/order/cancel/:id/withdraw 와 요청·응답·오류가 같습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_cancel_request_history_withdraw
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT. 지정하면 그 회원 주문의 요청만 철회합니다(아니면 404).

요청

위치 이름 타입 필수 기본값 설명
path id string O 취소 요청 ID
query·body user_id string 회원 지정(선택)

응답

200 OK — 취소 요청 응답 형식. status 는 cancel_withdrawn 입니다.

오류

HTTP error_code 언제
404 ORDER_CANCEL_REQUEST_NOT_FOUND 이 프로젝트에 없는 요청 ID. 회원을 지정했으면 다른 회원 주문의 요청도 404
404 USER_NOT_FOUND user_id 가 이 쇼핑몰 회원이 아님
403 USER_NOT_MATCH JWT 와 user_id 가 다른 회원
401 USER_SESSION_INVALID / USER_JWT_INVALID JWT 를 보냈지만 무효 — 회원 JWT
400 ORDER_CANCEL_REQUEST_WITHDRAW_UNABLE 승인 대기 상태가 아니라 철회할 수 없음
500 ORDER_CANCEL_REQUEST_WITHDRAW_CRITICAL_ERROR 예상하지 못한 오류

변경 이력

  • 2026-09-23 문서 최초 작성
  • 2026-09-28 JWT 또는 user_id 로 회원을 지정하면 그 회원 주문의 요청만 철회

POST /v1/order/confirm

분리 승인으로 설정된 주문의 결제를 승인합니다. 구매자가 결제 인증을 마친 뒤 승인 대기 중인 주문서를 가맹점 서버가 확정할 때 씁니다. 구독 주문은 구독 신청을 승인 처리합니다.

인증

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

요청

위치 이름 타입 필수 기본값 설명
body order_number string O 주문번호

응답

200 OK — 승인된 주문의 결제 응답 형식(order_number·order_name·price·status·receipt_status·receipt_id·purchased_at·products·user·order_url 등). 필드 설명은 주문을 봅니다.

오류

HTTP error_code 언제
404 ORDER_NOT_FOUND 이 프로젝트에 없는 주문번호
201 ORDER_COMPLETED_ALREADY 이미 승인 완료된 주문. 오류 형식이지만 상태는 201 입니다 — 재시도라면 성공으로 봐도 됩니다
400 ORDER_RECEIPT_NOT_CONFIRM_READY 승인 대기 상태가 아님(결제 인증 전 등)
400 ORDER_CONFIRM_PAYMENT_FAILED 결제사 승인 실패. message·payload 에 결제사 응답이 담깁니다
400 ORDER_REQUEST_TYPE_INVALID 승인할 수 없는 주문 종류

공통 오류는 오류를 봅니다.

변경 이력

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

GET /v1/order/result/:id

결제 결과를 주문번호로 조회합니다. 인증한 프로젝트의 주문만 보이며, 다른 프로젝트의 주문번호는 없는 주문과 같이 404 입니다.

구매자 화면에 결과를 보여 줄 때는 구매자 본인 확인이 들어간 GET /v1/orders/:id/result를 쓰세요.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_result_detail
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT. 지정하면 그 회원의 주문만 봅니다(다른 회원·비회원 주문은 404). 구독 주문 결과는 회원을 지정해야 볼 수 있습니다.

요청

위치 이름 타입 필수 기본값 설명
path id string O 주문번호

응답

200 OK

API·SDK 로 만든 주문(sdk: true)은 다음 형태입니다.

{
  "payload": {
    "order_number": "2609231234567890",
    "price": 30000,
    "status": 2,
    "receipt_status": 1
  },
  "extra": null,
  "sdk": true,
  "use_redirect": true,
  "redirect_url": "https://shop.example.com/order/done"
}json
필드 타입 설명
payload object 주문 결제 응답 형식 (주문)
extra object 주문 생성 때 넘긴 추가 정보
sdk boolean API·SDK 로 만든 주문인지
use_redirect boolean 결제 후 이동 주소를 쓰는지
redirect_url string 결제 후 이동 주소

쇼핑몰 화면에서 만든 주문(sdk: false)은 쇼핑몰 결과 화면용 암호화된 문자열 하나가 옵니다. 서버에서 주문 내용을 읽으려면 GET /v1/orders/:id를 쓰세요.

오류

HTTP error_code 언제
404 ORDER_NOT_FOUND 없는 주문번호, 또는 다른 프로젝트의 주문
400 ORDER_RESULT_LOOKUP_UNABLE_STATUS 결과를 볼 수 없는 상태(결제 진행 전 등)
400 ORDER_SUBSCRIBE_NEED_LOGIN 구독 주문인데 회원을 지정하지 않음
404 ORDER_NOT_FOUND (회원 지정) 그 회원의 주문이 아님
404 USER_NOT_FOUND user_id 가 이 쇼핑몰 회원이 아님
403 USER_NOT_MATCH JWT 와 user_id 가 다른 회원
401 USER_SESSION_INVALID / USER_JWT_INVALID JWT 를 보냈지만 무효 — 회원 JWT

공통 오류는 오류를 봅니다.

변경 이력

  • 2026-09-14 인증한 프로젝트의 주문만 조회 (다른 프로젝트 주문은 404)
  • 2026-09-23 문서 최초 작성
  • 2026-09-28 JWT 또는 user_id 로 회원 지정 — 구독 주문 결과 조회 가능(그 회원 주문만)

GET /v1/order/result/subscription

주문서(결제 준비) 단계의 결제 결과를 oid 로 조회합니다. 응답·오류 규칙은 GET /v1/order/result/:id와 같습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_result_subscription
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT. 지정하면 그 회원의 주문만 봅니다(다른 회원·비회원 주문은 404). 구독 주문 결과는 회원을 지정해야 볼 수 있습니다.

요청

위치 이름 타입 필수 기본값 설명
query oid string O 주문번호

응답

200 OK — GET /v1/order/result/:id와 같은 형식.

오류

HTTP error_code 언제
404 ORDER_NOT_FOUND 없는 주문번호, 또는 다른 프로젝트의 주문
400 ORDER_RESULT_LOOKUP_UNABLE_STATUS 결과를 볼 수 없는 상태
400 ORDER_SUBSCRIBE_NEED_LOGIN 구독 주문인데 회원을 지정하지 않음
404 ORDER_NOT_FOUND (회원 지정) 그 회원의 주문이 아님
404 USER_NOT_FOUND user_id 가 이 쇼핑몰 회원이 아님
403 USER_NOT_MATCH JWT 와 user_id 가 다른 회원
401 USER_SESSION_INVALID / USER_JWT_INVALID JWT 를 보냈지만 무효 — 회원 JWT

변경 이력

  • 2026-09-14 인증한 프로젝트의 주문만 조회 (다른 프로젝트 주문은 404)
  • 2026-09-23 문서 최초 작성
  • 2026-09-28 JWT 또는 user_id 로 회원 지정 — 구독 주문 결과 조회 가능(그 회원 주문만)

POST /v1/order/subscription/cancel

구독 결제 한 건(결제 트랜잭션)의 취소 금액을 계산해 취소 건을 만듭니다. 이 단계에서는 결제가 취소되지 않으며 상태는 0(계산됨)입니다. 만든 취소 건을 POST /v1/order/subscription/cancel/request-approval로 요청합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_transaction_cancel_create
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT. 구매자 요청이면 보내세요. 지정하면 그 회원의 구독 결제 건만 취소를 계산할 수 있고(아니면 403 SUBSCRIPTION_DENIED), 요청자(requester)는 구매자 로 저장합니다(cancel_requester 무시).

요청

위치 이름 타입 필수 기본값 설명
body order_subscription_transaction_id string O 취소할 구독 결제 건 ID
body price number O 취소 금액. 0 이면 남은 금액 전체
body tax_free_price number O 취소 면세 금액
body cancel_requester string 요청자 이름. 응답·관리자 승인 화면의 requester
body cancel_request_reason string 취소 사유. 응답·관리자 승인 화면의 message
body user_id string 구매자 요청의 회원(선택)
  • price·tax_free_price 를 빼면 500 이 납니다. 전체 취소는 둘 다 0 으로 보내세요.
  • 현재는 전체 취소(price: 0)만 정상 처리됩니다. 0 이 아닌 금액을 보내면 ORDER_SUBSCRIPTION_TRANSACTION_CANCELLED_PRICE_NOT_MATCH 또는 ORDER_SUBSCRIPTION_TRANSACTION_CANCELLED_TAX_PRICE_NOT_MATCH 로 거절됩니다.
  • parts 는 받지만 지금은 반영되지 않습니다.

응답

200 OK

{
  "order_subscription_transaction_cancel_id": "66f0d2...",
  "price": 9900,
  "tax_free_price": 0,
  "fee": 0,
  "status": 0,
  "unit": 1,
  "created_at": "2026-09-23T10:00:00+09:00"
}json
필드 타입 설명
order_subscription_transaction_cancel_id string 취소 건 ID. 승인 요청에 씁니다
price number 취소 금액
tax_free_price number 취소 면세 금액
fee number 환불 수수료
status integer 0 계산됨, 1 요청됨, 2 승인 완료, -1 승인 실패, -10 반려
unit integer 통화
requester · message · admin_name · reject_message string 요청자·사유·처리자·반려 사유 (있을 때)
approval_at · revoked_at string 승인·반려 시각, 철회 시각
created_at string 생성 시각

값이 없는 필드는 null 로 옵니다.

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_TRANSACTION_NOT_FOUND 없는 구독 결제 건, 또는 다른 쇼핑몰의 결제 건
403 SUBSCRIPTION_DENIED (회원 지정) 그 회원의 구독 결제 건이 아님
404 USER_NOT_FOUND user_id 가 이 쇼핑몰 회원이 아님
403 USER_NOT_MATCH JWT 와 user_id 가 다른 회원
401 USER_SESSION_INVALID / USER_JWT_INVALID JWT 를 보냈지만 무효 — 회원 JWT
400 ORDER_SUBSCRIPTION_TRANSACTION_CANCEL_ALREADY_REQUESTED 이 결제 건에 이미 요청된 취소가 있음
400 ORDER_CANCEL_ALREADY_COMPLETED 결제 완료가 아니거나 남은 금액이 없음
400 ORDER_SUBSCRIPTION_BILL_STATUS_NOT_DONE 결제 완료 상태가 아님
400 ORDER_SUBSCRIPTION_TRANSACTION_CANCELLED_PRICE_OVER 취소 금액이 남은 금액보다 큼
400 ORDER_SUBSCRIPTION_TRANSACTION_CANCELLED_TAX_PRICE_OVER 면세 금액이 남은 면세 금액보다 큼
400 ORDER_SUBSCRIPTION_TRANSACTION_CANCELLED_PRICE_NOT_MATCH 0 이 아닌 금액이 남은 금액과 다름
400 ORDER_SUBSCRIPTION_TRANSACTION_CANCELLED_TAX_PRICE_NOT_MATCH 0 이 아닌 금액을 보냄 (위 주의 참고)

공통 오류는 오류를 봅니다.

변경 이력

  • 2026-09-28 cancel_requester·cancel_request_reason 이 저장되지 않던 결함 수정(requester·message)
  • 2026-09-23 문서 최초 작성
  • 2026-09-28 다른 쇼핑몰의 결제 건 ID 로도 취소 건이 만들어지던 결함 수정(404), JWT 또는 user_id 로 회원 지정

POST /v1/order/subscription/cancel/request-approval

POST /v1/order/subscription/cancel로 만든 취소 건을 요청 상태로 바꿔 판매자 승인을 기다리게 합니다.

주의​: 현재 이 API 는 서버 결함으로 정상 처리되지 않습니다. 방금 만든(상태 0) 취소 건은 400 ORDER_SUBSCRIPTION_TRANSACTION_CANCEL_ALREADY_COMPLETED, 그 밖의 경우는 500 SERVER_ERROR 가 옵니다. 수정될 때까지 호출하지 마세요.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:order_subscription_transaction_cancel_request_approval
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT. 지정하면 그 회원의 구독 결제 건에 딸린 취소 건만 요청합니다(아니면 403 SUBSCRIPTION_DENIED).

요청

위치 이름 타입 필수 기본값 설명
body order_subscription_transaction_cancel_id string O 취소 건 ID
body user_id string 회원 지정(선택)

응답

현재는 성공 응답이 오지 않습니다(위 주의).

오류

HTTP error_code 언제
404 ORDER_SUBSCRIPTION_TRANSACTION_CANCEL_NOT_FOUND 없는 취소 건, 또는 다른 쇼핑몰의 취소 건
403 SUBSCRIPTION_DENIED (회원 지정) 그 회원의 구독 결제 건이 아님
404 USER_NOT_FOUND user_id 가 이 쇼핑몰 회원이 아님
403 USER_NOT_MATCH JWT 와 user_id 가 다른 회원
401 USER_SESSION_INVALID / USER_JWT_INVALID JWT 를 보냈지만 무효 — 회원 JWT
400 ORDER_SUBSCRIPTION_TRANSACTION_CANCEL_ALREADY_COMPLETED 요청할 수 있는 상태가 아닌 취소 건 (방금 만든 상태 0 포함 — 위 주의)
400 ORDER_SUBSCRIPTION_TRANSACTION_CANCELLED_PRICE_OVER 취소 금액이 남은 금액보다 큼
500 SERVER_ERROR 위 주의의 서버 결함

공통 오류는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성
  • 2026-09-28 다른 쇼핑몰의 취소 건 ID 로도 상태가 바뀔 수 있던 결함 수정(404), JWT 또는 user_id 로 회원 지정

함께 보기