예약결제는 이미 발급된 billing_key로 미래의 특정 시점에 한 번 결제되도록 예약하는 방식이에요.
가맹점 서버는 “어떤 빌링키로, 얼마를, 언제 결제할지”를 정해 예약을 등록하고, 응답으로 받은 reserve_id를 저장해야 해요. 부트페이가 그 예약을 보관하고 있다가 예약 시각이 되면 저장된 빌링키로 결제를 대신 실행하고, 가맹점 서버는 웹훅과 결제 조회로 결과를 확정해요.
자동결제 문서를 먼저 봤다면 이렇게 이해하면 쉬워요. 두 방식 모두 빌링키로 결제하지만 호출 주체가 달라요. 자동결제는 가맹점 서버가 청구 시점마다 직접 결제 요청 API를 호출하고, 예약결제는 가맹점 서버가 실행 시각을 미리 지정해 그 호출을 부트페이에 맡겨두는 구조예요.
영상으로 보기
결제 예약하기 · 7분 33초
핵심 요약
- 예약결제의 공통 준비물도
billing_key예요. 아직 빌링키가 없다면 빌링키 발급을 먼저 연동해요. - 예약 등록 API 응답은 결제 성공이 아니라 “미래 결제 예약 성공”이에요.
reserve_id,order_id,billing_key,reserve_execute_at,price는 조회·취소·웹훅 매칭을 위해 저장해야 해요.- 실행 전에는 예약 취소, 실행 후에는
receipt_id기준 결제 취소를 사용해요. - 결제수단 변경·빌링키 삭제 순서는 운영 주의사항에서 먼저 정해요.
- 실행 시각은 현재로부터 2개월 이내만 등록할 수 있어요.
- 빌링키 하나당 대기(실행 전) 예약은 10건까지만 쌓을 수 있어요.
- 같은 빌링키 안에서
order_id는 재사용할 수 없어요. 취소되거나 실행이 끝난 예약의order_id도 마찬가지예요.
세 제약 모두 장기 구독에는 맞지 않아요. 매월 반복 청구라면 예약결제 대신 자동결제로 설계해요.
동작 방식
가맹점 서버는 예약 등록 시점에 실행 시각을 확정해야 해요. 등록 후에는 reserve_id 기준으로 예약을 조회하거나 취소하고, 예약 실행 결과는 웹훅으로 받은 뒤 receipt_id로 다시 조회해 내부 주문 상태와 맞춰야 해요.
이런 상황이라면
| 상황 | 판단 |
|---|---|
| 숙박 체크인 당일 잔금 결제 | 적합해요. 예약 확정 시점에 미래 결제를 등록해요 |
| 수업·상담 예약일 하루 전 결제 | 적합해요. 예약 취소 정책과 함께 운영해요 |
| 렌터카 반납 후 정산 예정 금액 결제 | 가능해요. 금액 확정 시점과 예약 변경 가능성을 함께 봐요 |
| 매월 구독료 청구 | 가능하지만 회차·재시도 제어가 필요하면 자동결제가 더 적합해요 |
| 결제수단 변경이 자주 발생 | 기존 예약 취소 후 새 빌링키로 재예약하는 흐름이 필요해요 |
자동결제와의 차이
| 항목 | 예약결제 | 자동결제 |
|---|---|---|
| 빌링키 | 필요 | 필요 |
| 실행 시각 결정 | 가맹점 서버가 예약 등록 시 reserve_execute_at 지정 |
가맹점 서버가 청구 시점마다 직접 결정 |
| 실행 방식 | 부트페이가 예약을 보관했다가 예약 시각에 빌링키 결제를 대신 실행 | 가맹점 서버가 해당 시점에 빌링키 결제 요청 API 호출 |
| 서버 스케줄러 | 보통 불필요 | 필요 |
| 결과 확인 | 예약 실행 후 웹훅 + 결제 조회 | 즉시 응답 + 웹훅 + 결제 조회 |
| 등록 제약 | 2개월 이내, 빌링키당 대기 10건, order_id 재사용 불가 |
없음 (청구 시점마다 직접 호출) |
| 대표 사례 | 체크인 결제, 예약 잔금, 미래 1회 청구 | 월 구독, 후불 정산, 사용량 과금 |
예약결제 구성 요소
| 구성 요소 | 가맹점이 해야 할 일 | 관련 문서 |
|---|---|---|
| 빌링키 준비 | 고객 결제수단 등록 후 billing_key 저장 |
빌링키 발급 |
| 예약 등록 | billing_key, 금액, 실행 시각으로 예약 생성 |
결제 예약 |
| 예약 조회 | reserve_id로 대기·완료·실패·취소 상태 확인 |
예약 조회 |
| 예약 취소 | 실행 전 예약을 제거 | 예약 취소 |
| 운영 처리 | 결제수단 변경, 빌링키 삭제, 웹훅 멱등 처리 설계 | 운영 주의사항 |
예약 API 응답은 “미래 결제 예약이 등록됐다”는 뜻이에요. 실제 결제 성공 여부는 예약 시간이 지난 뒤 웹훅과 결제 조회으로 확인해야 해요.
빌링키 만료는 두 갈래로 나뉘어요.
등록 시점에 이미 알 수 있는 만료 — 예약 실행 시각이 빌링키 만료 시각보다 뒤라면 예약 등록 자체가 거부돼요(SR_EXPIRED_BK_EXECUTE_OVER, 2517). 이 경우 빌링키를 먼저 새로 발급받고 예약해야 해요.
등록 이후에 생기는 만료 — 등록은 통과했지만 실행 시각이 될 때까지 고객이 결제수단을 해지하거나 빌링키가 삭제될 수 있어요. 이건 등록 시점에 막을 수 없고 예약 실행 시 결제 실패로 나타나요(예약 상태 -1). 실행일이 먼 예약일수록 실행 직전 빌링키 조회로 유효성을 확인하고, 실패를 감지하면 고객에게 결제수단 갱신을 안내해요.