예약결제는 API 호출 자체보다 운영 순서에서 사고가 나기 쉬워요. 특히 예약 취소, 결제 취소, 빌링키 삭제는 서로 다른 작업이에요. 고객 화면에서는 모두 “결제수단 해지”처럼 보일 수 있지만, 서버에서는 어떤 예약을 먼저 멈추고 어떤 토큰을 삭제할지 순서를 정해야 해요.
핵심 요약
- 빌링키 삭제는 결제수단 토큰 삭제이고, 예약 취소는 미래 결제 예약 제거예요.
- 고객이 결제수단을 바꾸면 기존 예약을 취소하고 새 빌링키로 다시 예약해야 해요.
- 예약 실행 전에는 예약 취소 API, 실행 후에는 일반 결제 취소 API를 사용해요.
- 웹훅은 결과 신호로만 보고, 최종 처리는
receipt_id조회와 내부 주문 비교로 확정해야 해요. - 시간대는 DB 저장 기준과 고객 표시 기준을 분리해요.
취소·변경 흐름
1빌링키 삭제 전에 예약을 먼저 확인해요
빌링키 삭제는 결제수단 토큰을 삭제하는 작업이고, 예약 취소는 미래 결제 예약을 제거하는 작업이에요. 둘은 같은 작업이 아니에요.
빌링키를 삭제한다고 해서 이미 등록된 예약결제가 자동으로 취소된다고 가정하면 안 돼요. 고객이 예약 결제를 중단하거나 결제수단을 해지하는 경우에는 먼저 대기 중인 예약을 조회·취소하고, 그 다음 필요하면 빌링키를 삭제해요.
| 순서 | 작업 | 관련 문서 |
|---|---|---|
| 1 | 고객의 대기 중 예약을 조회해요 | 예약 조회 |
| 2 | 실행 전 예약을 취소해요 | 예약 취소 |
| 3 | 서비스 DB에서 예약 상태를 cancelled로 바꿔요 |
— |
| 4 | 더 이상 결제수단을 쓰지 않으면 빌링키를 삭제해요 | 빌링키 삭제 |
| 5 | 서비스 DB의 빌링키 상태를 revoked로 바꿔요 |
데이터 저장 설계 |
2실행 전 취소와 실행 후 취소를 나눠요
예약 시간이 지나 실제 결제가 실행된 뒤에는 예약 취소 API로 되돌릴 수 없어요. 그때는 일반 결제 취소 API를 사용해야 해요.
| 상황 | 사용 API | 저장 상태 예시 |
|---|---|---|
| 예약 등록만 됨 | 예약 취소 | reserved → cancelled |
| 예약 실행 여부가 불확실함 | 예약 조회 후 판단 | reserved / paid / failed 확인 |
| 결제가 이미 완료됨 | 결제 취소 | paid → refunded 또는 cancelled |
| 웹훅은 왔지만 내부 처리 실패 | 결제 조회 후 멱등 처리 | paid_pending_sync → paid |
고객 화면의 “예약 취소”와 “결제 환불” 문구를 분리해요. 예약 실행 전에는 결제 자체가 아직 발생하지 않았으므로 환불이 아니라 예약 취소예요.
3결제수단 변경은 기존 예약 취소 후 재예약해요
고객이 카드를 바꾸면 새 빌링키가 생겨요. 기존 예약이 예전 빌링키로 등록되어 있다면 새 빌링키로 자동 변경된다고 가정하면 안 돼요.
| 순서 | 작업 |
|---|---|
| 1 | 새 결제수단으로 빌링키 발급 |
| 2 | 기존 reserve_id로 예약 취소 |
| 3 | 새 billing_key로 결제 예약 재등록 |
| 4 | 새 reserve_id 저장 |
| 5 | 기존 빌링키를 더 쓰지 않으면 빌링키 삭제 |
이 순서를 지키면 “카드는 바꿨는데 예약은 예전 카드로 실행되는” 상황을 줄일 수 있어요.
4reserve_id와 order_id를 둘 다 저장해요
예약 등록 응답은 나중에 조회·취소·웹훅 매칭에 필요해요. 최소한 아래 값은 저장해야 해요.
| 필드 | 이유 |
|---|---|
reserve_id |
예약 조회·취소의 기준 ID |
order_id |
가맹점 주문/예약과 Bootpay 결제를 매칭 |
billing_key 또는 내부 billing key ID |
어떤 결제수단으로 예약했는지 추적 |
reserve_execute_at |
고객 안내와 실행 전 취소 가능성 판단 |
price |
웹훅·결제 조회 시 금액 검증 |
status |
reserved, cancelled, paid, failed 등 내부 상태 관리 |
5웹훅을 최종 처리 기준으로 삼지 말고 다시 조회해요
예약 등록 성공은 결제 성공이 아니에요. 예약 시간이 지나면 결제 결과가 웹훅으로 전달되지만, 웹훅 payload만 믿고 주문을 확정하면 안 돼요.
| 단계 | 서버 처리 |
|---|---|
| 웹훅 수신 | 빠르게 HTTP 200 응답 |
| 영수증 확인 | receipt_id로 결제 조회 호출 |
| 내부 주문 비교 | 금액, 주문번호, 상태, 중복 처리 여부 확인 |
| 상태 확정 | 검증 성공 시 내부 예약/주문 상태 업데이트 |
웹훅 처리의 공통 설계는 웹훅을 함께 봐요.
6시간대 기준을 하나로 고정해요
reserve_execute_at은 사람에게 보이는 날짜와 서버가 저장하는 시간이 어긋나기 쉬워요.
- DB에는 UTC 기준으로 저장해요.
- 고객 화면에는 서비스 기준 시간대(KST 등)로 변환해 보여줘요.
- API 요청 값과 고객 안내 문구가 같은 기준인지 로그에 남겨요.
- 실행 직전 예약 등록은 PG사 처리 지연 가능성을 고려해 제한해요.