이 문서는 등록된 예약결제를 reserve_id로 조회하는 방법을 설명해요.
예약 조회는 실행 전 취소 가능 여부를 확인하거나, 웹훅 처리 실패 후 예약 상태를 보정할 때 사용해요.
핵심 요약
- 예약 조회는
reserve_id기준으로 대기·완료·실패·취소 상태를 확인해요. - 예약 취소 전에는 먼저 조회해서 아직 실행 전인지 확인하는 흐름이 안전해요.
- 이미 결제가 실행된 예약은 예약 취소가 아니라
receipt_id기준 결제 취소 흐름으로 가야 해요. - 내부 DB의 예약 상태와 Bootpay 조회 결과가 다르면 조회 결과를 기준으로 보정해요.
상태 흐름
API 엔드포인트
GET
https://api.bootpay.co.kr/v2/subscribe/payment/reserve/:reserve_idBasic Auth요청 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
reserve_id |
String | 필수 | 예약 결제 ID (URL 파라미터) |
코드 예제
import { Bootpay } from '@bootpay/backend-js'
Bootpay.setConfiguration({
client_key: '[ Client Key ]',
secret_key: '[ Secret Key ]'
})
try {
const response = await Bootpay.subscribePaymentReserveLookup(
'6261104e1fc19202e6f9420e'
)
console.log(response)
} catch (e) {
console.log(e)
}javascriptfrom bootpay_backend import BootpayBackend
bootpay = BootpayBackend('APPLICATION_ID', 'PRIVATE_KEY')
response = bootpay.subscribe_payment_reserve_lookup('6261104e1fc19202e6f9420e')
print(response)pythonuse Bootpay\ServerPhp\BootpayApi;
BootpayApi::setConfiguration('APPLICATION_ID', 'PRIVATE_KEY');
$response = BootpayApi::subscribePaymentReserveLookup('6261104e1fc19202e6f9420e');
print_r($response);phpimport kr.co.bootpay.pg.Bootpay;
Bootpay bootpay = new Bootpay("APPLICATION_ID", "PRIVATE_KEY");
var response = bootpay.reserveSubscribeLookup("6261104e1fc19202e6f9420e");
System.out.println(response);javabootpay = Bootpay::Api.new(application_id: 'APPLICATION_ID', private_key: 'PRIVATE_KEY')
response = bootpay.request(
method: :get,
uri: 'subscribe/payment/reserve/6261104e1fc19202e6f9420e'
)
puts response.datarubyimport "github.com/bootpay/backend-go/v2"
api := bootpay.NewAPI("APPLICATION_ID", "PRIVATE_KEY", nil, "")
response, err := api.ReserveSubscribeLookup("6261104e1fc19202e6f9420e")
if err != nil {
log.Fatal(err)
}
fmt.Println(response)gousing Bootpay;
var bootpay = new BootpayApi("APPLICATION_ID", "PRIVATE_KEY");
var response = await bootpay.ReserveSubscribeLookup("6261104e1fc19202e6f9420e");
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);csharp응답
예약 조회 결과는 status를 기준으로 내부 예약 상태를 보정해요. 실행이 끝난 예약은 receipt_id로 결제 조회를 한 번 더 호출해 금액과 결제 상태를 확인해야 해요.
{
"price": 9900,
"tax_free": 0,
"billing_key": "615d00f0197c300036b4fef5",
"order_id": "reserve_1705289520000",
"order_name": "예약 잔금 결제",
"reserve_requested_at": "2025-01-15T14:32:00+09:00",
"reserve_execute_at": "2025-02-01T09:00:00+09:00",
"reserve_started_at": null,
"reserve_finished_at": null,
"reserve_revoked_at": null,
"feedback_url": "https://example.com/webhook",
"content_type": "application/json",
"status": 0
}json{
"price": 9900,
"tax_free": 0,
"billing_key": "615d00f0197c300036b4fef5",
"order_id": "reserve_1705289520000",
"order_name": "예약 잔금 결제",
"receipt_id": "6244f60c1fc19202e42e8c4e",
"reserve_requested_at": "2025-01-15T14:32:00+09:00",
"reserve_execute_at": "2025-02-01T09:00:00+09:00",
"reserve_started_at": "2025-02-01T09:00:00+09:00",
"reserve_finished_at": "2025-02-01T09:00:03+09:00",
"reserve_revoked_at": null,
"status": 1
}json{
"price": 9900,
"tax_free": 0,
"billing_key": "615d00f0197c300036b4fef5",
"order_id": "reserve_1705289520000",
"order_name": "예약 잔금 결제",
"receipt_id": "6244f60c1fc19202e42e8c4e",
"reserve_requested_at": "2025-01-15T14:32:00+09:00",
"reserve_execute_at": "2025-02-01T09:00:00+09:00",
"reserve_started_at": "2025-02-01T09:00:00+09:00",
"reserve_finished_at": "2025-02-01T09:00:03+09:00",
"reserve_revoked_at": null,
"status": 2
}json{
"price": 9900,
"tax_free": 0,
"billing_key": "615d00f0197c300036b4fef5",
"order_id": "reserve_1705289520000",
"order_name": "예약 잔금 결제",
"reserve_requested_at": "2025-01-15T14:32:00+09:00",
"reserve_execute_at": "2025-02-01T09:00:00+09:00",
"reserve_started_at": null,
"reserve_finished_at": null,
"reserve_revoked_at": null,
"status": -1
}json{
"price": 9900,
"tax_free": 0,
"billing_key": "615d00f0197c300036b4fef5",
"order_id": "reserve_1705289520000",
"order_name": "예약 잔금 결제",
"reserve_requested_at": "2025-01-15T14:32:00+09:00",
"reserve_execute_at": "2025-02-01T09:00:00+09:00",
"reserve_started_at": null,
"reserve_finished_at": null,
"reserve_revoked_at": "2025-01-20T10:10:00+09:00",
"status": 3
}json응답 파라미터
| 파라미터 | 타입 | 설명 |
|---|---|---|
| price | Number | 결제 금액 |
| tax_free | Number | 비과세 금액 |
| billing_key | String | 빌링키 |
| order_id | String | 가맹점 주문번호 |
| order_name | String | 주문명 |
| reserve_requested_at | Date | 예약 요청 시간 |
| reserve_execute_at | Date | 예약 실행 시간 |
| reserve_started_at | Date | 실행 시작 시간 |
| reserve_finished_at | Date | 실행 완료 시간 |
| reserve_revoked_at | Date | 예약 취소 시간 |
| feedback_url | String | 웹훅 수신 URL |
| content_type | String | 웹훅 데이터 타입 |
| version | Number | API 버전 (1 또는 2) |
| status | Number | 예약 결제 상태 |
status 값
| 값 | 설명 | 서버 처리 |
|---|---|---|
| -1 | 예약 실패 | 예약 등록·실행 준비 단계의 실패 사유를 확인해요 |
| 0 | 대기 중 (실행 전) | 필요하면 예약 취소 가능 |
| 1 | 결제 완료 | receipt_id 기준 결제 조회 후 주문 확정 |
| 2 | 빌링 결제 실패 | 실패 사유 확인 후 재시도 또는 고객 안내 |
| 3 | 예약 취소됨 | 내부 예약 상태를 cancelled로 보정 |
상태 보정 기준
내부 DB에는 reserved, cancelled, paid, failed처럼 서비스 운영에 맞는 상태값을 두고, Bootpay 조회 결과를 기준으로 보정해요. 같은 reserve_id로 여러 번 조회해도 같은 결과가 반영되도록 멱등 처리해야 해요.
에러 코드
공통 에러
인증·권한 관련 에러는 에러 코드표를 참고해요.
| 코드 | 메시지 | 대처 방법 |
|---|---|---|
BS_NOT_FOUND (2504) |
예약결제 정보를 찾지 못했다 | reserve_id가 올바른지 확인해요 |
BS_UNAUTHORIZED (2509) |
예약결제 접근 권한 없음 | 해당 예약의 소유자 계정으로 요청해요 |