결제가 끝난 주문을 가맹점 서버에서 처리하는 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를 씁니다.
취소 요청의 흐름
POST /v1/order/cancel로 취소 요청을 만듭니다. 요청 상태는cancel_requested입니다.cancel_immediately=true면 승인 없이 바로 결제를 취소합니다.- 판매자가
PUT /v1/order/cancel/:id/approve로 승인하면 결제가 취소되고(cancel_approved),reject로 반려하면cancel_rejected가 됩니다. - 구매자가 요청을 거둬들이면
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
}jsonlist 항목은 위 취소 요청 응답 형식의 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. 구매자 요청이면 보내세요. 지정하면 그 회원의 구독 결제 건만 취소를 계산할 수 있고(아니면 403SUBSCRIPTION_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. 지정하면 그 회원의 구독 결제 건에 딸린 취소 건만 요청합니다(아니면 403SUBSCRIPTION_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로 회원 지정
