주문 취소 | Bootpay 커머스 매뉴얼

주문 취소 요청부터 후속 처리 분기까지 한 엔드포인트로 열어요.

결제된 주문에 대해 전체 또는 부분 취소를 요청해요.

API 엔드포인트

POSThttps://api.bootapi.com/v1/order/cancel-refund/cancelBasic Auth

취소 유형

유형	설명
전체 취소	결제된 전체 금액을 한 번에 취소
부분 취소	결제 금액 중 일부만 선택적으로 취소 (일부 카드사 미지원)

취소 방식

방식	파라미터	설명
상품 기준	`cancel_products`	특정 상품을 선택하여 취소
금액 기준	`cancel_price`	금액을 직접 지정하여 취소

주문 취소 요청 -> 취소 범위?
취소 범위? -전액-> 전체 취소 / cancel_price 미지정
취소 범위? -일부-> 부분 취소 방식?
부분 취소 방식? -> 상품 기준 / cancel_products
부분 취소 방식? -> 금액 기준 / cancel_price

요청 파라미터

파라미터	타입	필수	설명
`order_number`	String	필수	주문 생성시 발급된 주문 번호
`request_cancel_parameters`	Object	필수	취소 요청 파라미터
`request_cancel_parameters.cancel_id`	String	선택	가맹점 취소 ID (중복 시 에러)
`request_cancel_parameters.cancel_price`	Integer	선택	취소 금액 (0 또는 미지정 시 전액)
`request_cancel_parameters.cancel_tax_free_price`	Integer	선택	취소 비과세 금액
`request_cancel_parameters.cancel_requester`	String	선택	취소 요청자명
`request_cancel_parameters.cancel_message`	String	선택	취소 사유
`request_cancel_parameters.cancel_products`	Array	선택	취소할 상품 목록
`request_cancel_parameters.cancel_immediately`	Boolean	선택	즉시 취소 여부

코드 예제

const { BootpayCommerce } = require('@bootpay/backend-js')

const commerce = new BootpayCommerce({
    client_key: 'your-commerce-client-key',
    secret_key: 'your-commerce-secret-key',
    mode: 'production'
})

const response = await commerce.order.cancel({
    order_number: 'ORDER_12345',
    request_cancel_parameters: {
        cancel_price: 10000,
        cancel_message: '고객 요청에 의한 취소',
        cancel_requester: '관리자'
    }
})
console.log(response)javascript

from bootpay_backend import BootpayCommerce

commerce = BootpayCommerce(
    client_key='your-commerce-client-key',
    secret_key='your-commerce-secret-key',
    mode='production'
)

response = commerce.order.cancel(
    order_number='ORDER_12345',
    request_cancel_parameters={
        'cancel_price': 10000,
        'cancel_message': '고객 요청에 의한 취소',
        'cancel_requester': '관리자'
    }
)
print(response)python

use Bootpay\ServerPhp\BootpayCommerceApi;

$commerce = new BootpayCommerceApi('your-commerce-client-key', 'your-commerce-secret-key');
$response = $commerce->order->cancel([
    'order_number' => 'ORDER_12345',
    'request_cancel_parameters' => [
        'cancel_price' => 10000,
        'cancel_message' => '고객 요청에 의한 취소',
        'cancel_requester' => '관리자'
    ]
]);
print_r($response);php

import kr.co.bootpay.store.BootpayStore;
import kr.co.bootpay.store.model.request.TokenPayload;

TokenPayload tp = new TokenPayload("your-commerce-client-key", "your-commerce-secret-key");
BootpayStore commerce = new BootpayStore(tp);
HashMap<String, Object> cancelParams = new HashMap<>();
cancelParams.put("cancel_price", 10000);
cancelParams.put("cancel_message", "고객 요청에 의한 취소");
cancelParams.put("cancel_requester", "관리자");

HashMap<String, Object> params = new HashMap<>();
params.put("order_number", "ORDER_12345");
params.put("request_cancel_parameters", cancelParams);

HashMap<String, Object> response = commerce.order.cancel(params);
System.out.println(response);java

commerce = BootpayStore::Api.new('your-commerce-client-key', 'your-commerce-secret-key')
response = commerce.order_cancel(
  order_number: 'ORDER_12345',
  request_cancel_parameters: {
    cancel_price: 10000,
    cancel_message: '고객 요청에 의한 취소',
    cancel_requester: '관리자'
  }
)
puts responseruby

import "github.com/bootpay/backend-go/v2"

commerce := bootpay.NewCommerceApi("your-commerce-client-key", "your-commerce-secret-key")
response, err := commerce.Order.Cancel(bootpay.OrderCancelParams{
    OrderNumber: "ORDER_12345",
    RequestCancelParameters: bootpay.CancelParameters{
        CancelPrice:     10000,
        CancelMessage:   "고객 요청에 의한 취소",
        CancelRequester: "관리자",
    },
})
fmt.Println(response)go

using Bootpay.Commerce;

var commerce = new BootpayCommerceApi("your-commerce-client-key", "your-commerce-secret-key");
var response = await commerce.Order.Cancel(new {
    order_number = "ORDER_12345",
    request_cancel_parameters = new {
        cancel_price = 10000,
        cancel_message = "고객 요청에 의한 취소",
        cancel_requester = "관리자"
    }
});
Console.WriteLine(response);csharp

응답

성공 응답

{
  "order_id": "68707c59b0eacea5cd974efd",
  "order_number": "ORDER_12345",
  "status": 2,
  "cancel_status": 1,
  "cancel_request_history": {
    "id": "687a1b2c3d4e5f6789012345",
    "cancel_price": 10000,
    "cancel_message": "고객 요청에 의한 취소",
    "status": 0,
    "created_at": "2025-07-11T02:52:09Z"
  }
}json

에러 응답

{
  "status": 400,
  "code": 3700,
  "message": "주문내역을 찾지 못했습니다.",
  "data": null
}json

취소 상태 코드

값	상태	설명
0	없음	취소 요청 없음
`PROCESS_DUPLICATED`	이미 처리된 요청이에요	취소 요청 대기
2	취소완료	취소 처리 완료

에러 코드

인증·권한 관련 에러는 에러 코드표를 참고해요.

코드	메시지	대처 방법
`ORDER_NOT_FOUND`	주문내역을 찾지 못했어요.	order_id를 확인해요
`ORDER_CANCEL_PRICE_OVER`	취소 가능한 금액보다 취소 요청 금액이 더 커요.	남은 취소 가능 금액을 확인해요
`ORDER_STATUS_NOT_CANCELABLE`	취소가 불가능한 주문정보예요.	주문 상태를 확인해요
`ORDER_PRODUCT_ALREADY_CANCELLED`	이미 취소된 상품이에요.	주문 상품의 취소 상태를 확인해요

취소는 매입 완료 후 진행돼요. 환불은 영업일 기준 3~5일 이내 결제자에게 반환돼요.