본문으로 건너뛰기

예약/결제

사용자의 예약 조회, 결제 진행, 취소 및 내역 확인 API입니다.

결제 흐름​

결제는 3단계로 진행됩니다:

예약 불가 리스트 조회​

GET /reservations

지점/날짜/시간 기준으로 예약 불가능한 슬롯 목록을 조회합니다. 클라이언트는 이 데이터를 기반으로 예약 가능한 시간대를 표시합니다.

Headers​

이름필수설명
CookieX세션 쿠키 (비로그인 접근 가능)

Query Parameters​

파라미터타입필수설명
branchStringO지점 영문명 (지점 코드 참고)
base_dateStringO기준 날짜 (yyyyMMdd)
base_hourStringO기준 시간 (0 ~ 23)
GET /api/reservations?branch=Gwanghwamun&base_date=20260305&base_hour=14

Response​

{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": {
    "booking": ["1-202603051400", "1-202603051410"],
    "paid": ["2-202603051500", "2-202603051510", "2-202603051520"],
    "bookingMargin": ["1-202603051350"],
    "paidMargin": ["2-202603051450", "2-202603051530"],
    "disabledRooms": ["5"]
  }
}

data 필드

필드타입설명
bookingString[]예약 진행 중인 슬롯 ({room}-{YYYYMMDDHHmm})
paidString[]결제 완료 슬롯
bookingMarginString[]예약 진행 중 마진 슬롯 (전후 10분 버퍼)
paidMarginString[]결제 완료 마진 슬롯 (전후 10분 버퍼)
disabledRoomsString[]비활성화된 룸 번호
슬롯 형식

슬롯은 {방번호}-{YYYYMMDDHHmm} 형식입니다. 10분 단위로 표현되며, 예를 들어 2-202603051500은 2번 방의 15:00~15:10 슬롯입니다.

마진 슬롯

마진 슬롯은 예약 전후 10분 버퍼입니다. 예약 14:00~15:00이면 마진은 13:50(전) + 15:00(후)입니다. 클라이언트는 마진 슬롯도 선택 불가로 표시해야 합니다.

V2 캘린더 조회​

GET /v2/branches/{branch}/calendar

지점의 월별 날짜 상태(영업/휴무/공휴일)를 조회합니다.

Path Parameters​

파라미터타입필수설명
branchStringO지점 영문명 (지점 코드 참고)

Query Parameters​

파라미터타입필수설명
yearMonthStringO조회 연월 (YYYY-MM)
GET /api/v2/branches/Gwanghwamun/calendar?yearMonth=2026-03

Response​

{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": {
    "yearMonth": "2026-03",
    "dates": [
      { "date": "2026-03-01", "status": "available", "reason": null },
      { "date": "2026-03-02", "status": "closed", "reason": "정기 휴무" },
      { "date": "2026-03-03", "status": "available", "reason": null }
    ]
  }
}

data 필드

필드타입설명
yearMonthString조회한 연월
datesArray날짜별 상태 목록

dates 항목

필드타입Nullable설명
dateStringN날짜 (YYYY-MM-DD)
statusStringNavailable / closed / holiday
reasonStringY휴무/공휴일 사유

V2 룸/슬롯 조회​

GET /v2/branches/{branch}/reservations

지점의 룸 목록과 시간대별 예약 불가 슬롯을 조회합니다. 룸 정보에는 등급(grade)과 가격이 포함됩니다.

Path Parameters​

파라미터타입필수설명
branchStringO지점 영문명 (지점 코드 참고)

Query Parameters​

파라미터타입필수기본값설명
dateStringO-기준 날짜 (YYYY-MM-DD)
baseHourintO-시작 시간 (0~23)
hoursintX4표시할 시간 범위
GET /api/v2/branches/Gwanghwamun/reservations?date=2026-03-05&baseHour=14&hours=4

Response​

{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": {
    "rooms": [
      {
        "roomNo": "1",
        "machine": "Capsule A",
        "grade": "Stella",
        "enabled": true,
        "pricing": {
          "min10": 2500,
          "min30": 6000,
          "min60": 10000
        }
      },
      {
        "roomNo": "2",
        "machine": "Capsule B",
        "grade": "Premium",
        "enabled": true,
        "pricing": {
          "min10": 2000,
          "min30": 5000,
          "min60": 8000
        }
      }
    ],
    "unavailableSlots": {
      "paid": ["1-202603051500", "1-202603051510", "1-202603051520"],
      "booking": ["2-202603051400"],
      "paidMargin": ["1-202603051450", "1-202603051530"],
      "bookingMargin": ["2-202603051350"],
      "breakTime": [],
      "closedTime": []
    }
  }
}

rooms 항목

필드타입Nullable설명
roomNoStringN방 번호
machineStringN머신(침대) 이름
gradeStringY등급 (Stella / Crystal / Superb / Premium / Gold / Standard / Normal)
enabledbooleanN활성 여부
pricingObjectN가격 정보

pricing

필드타입Nullable설명
min10IntegerY10분당 가격
min30IntegerY30분당 가격
min60IntegerY60분당 가격

unavailableSlots

필드타입설명
paidString[]결제 완료 슬롯
bookingString[]예약 진행 중 슬롯
paidMarginString[]결제 완료 마진 슬롯
bookingMarginString[]예약 진행 중 마진 슬롯
breakTimeString[]휴게시간 슬롯
closedTimeString[]영업 종료 슬롯
정렬 순서

rooms는 가격 내림차순 → 같은 가격일 경우 방번호(숫자) 오름차순으로 정렬됩니다.

예약 진행 (Step 1)​

POST /reservation

예약 가능 여부를 검증하고, PAY_SESSIONID 쿠키를 발급합니다. 이 쿠키는 이후 결제 과정에서 예약 정보를 식별하는 데 사용됩니다.

뒤로가기 시 취소 필수

예약 진행 후 사용자가 뒤로가기를 누르면 반드시 DELETE /reservation을 호출하여 Redis 점유 자원을 해제해야 합니다.

Headers​

이름필수설명
Content-TypeOapplication/json

Request Body​

파라미터타입필수설명
branchStringO지점 영문명 (지점 코드 참고)
roomintO방 번호
startDateTimeStringO시작 시간 (YYYYMMDDHHmm)
endDateTimeStringO종료 시간 (YYYYMMDDHHmm)
요청 예시
{
  "branch": "Gwanghwamun",
  "room": 1,
  "startDateTime": "202603051400",
  "endDateTime": "202603051600"
}

Response​

성공 시 PAY_SESSIONID 쿠키가 Set-Cookie 헤더에 포함됩니다.

Set-Cookie: PAY_SESSIONID=abc123; Path=/; HttpOnly
{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": null
}
최대 예약 시간

최대 예약 시간은 5시간입니다. 초과 시 400 에러가 반환됩니다.

결제 등록 (Step 2)​

POST /payment

토스 위젯 호출 전 결제 데이터를 등록합니다. Step 1에서 발급된 PAY_SESSIONID 쿠키가 필요합니다.

Headers​

이름필수설명
Content-TypeOapplication/json
CookieOPAY_SESSIONID (Step 1에서 발급)

Request Body​

파라미터타입필수설명
amountintO결제 금액
nameStringO예약자 이름 (최대 50자)
mobileNumStringO휴대폰 번호 (최대 20자)
emailStringX이메일
요청 예시
{
  "amount": 12000,
  "name": "홍길동",
  "mobileNum": "01012345678",
  "email": "user@example.com"
}

Response​

{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": {
    "orderId": "ORD-20260305-abc123"
  }
}

data 필드

필드타입설명
orderIdString토스 위젯에 전달할 주문 ID

결제 확인 (Step 3)​

POST /payment/confirm

토스 위젯 결제 완료 후 서버에서 최종 승인합니다. 성공 시 doorlockKey가 생성되고, 카카오 알림톡이 발송됩니다.

Headers​

이름필수설명
Content-TypeOapplication/json

Request Body​

파라미터타입필수설명
paymentKeyStringO토스 결제 키
orderIdStringOStep 2에서 받은 주문 ID
amountintO결제 금액 (위변조 검증용)
요청 예시
{
  "paymentKey": "tgen_20260305_abc123",
  "orderId": "ORD-20260305-abc123",
  "amount": 12000
}

Response​

{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": {
    "branch": "Gwanghwamun",
    "roomNo": "1",
    "startDateTime": "202603051400",
    "endDateTime": "202603051550",
    "refundableDateTime": "202603051330",
    "mobileNum": "01012345678",
    "email": "user@example.com",
    "paymentMethod": "카드",
    "virtualaccountAccountNumber": null,
    "virtualaccountBankName": null,
    "virtualaccountAmount": null,
    "virtualaccountCustomerName": null,
    "virtualaccountDueDate": null
  }
}

data 필드

필드타입Nullable설명
branchStringN지점 영문명
roomNoStringN방 번호
startDateTimeStringN시작 시간 (YYYYMMDDHHmm)
endDateTimeStringN종료 시간 (YYYYMMDDHHmm)
refundableDateTimeStringN환불 가능 시한 (YYYYMMDDHHmm)
mobileNumStringN휴대폰 번호
emailStringY이메일
paymentMethodStringN카드 / 간편결제 / 가상계좌 / 휴대폰
virtualaccountAccountNumberStringY가상계좌 번호 (가상계좌 결제 시)
virtualaccountBankNameStringY가상계좌 은행명
virtualaccountAmountIntegerY입금 금액
virtualaccountCustomerNameStringY예금주명
virtualaccountDueDateStringY입금 기한 (ISO 8601)
endDateTime

DB에 저장되는 endDateTime은 실제 종료 시간보다 10분 앞선 시간입니다. 예를 들어 실제 종료가 16:00이면 DB에는 15:50으로 저장됩니다.

결제 완료 시

카드 결제 완료 시 doorlockKey(UUID)가 생성되어 Pay 테이블에 저장됩니다. 이 키는 도어락 해제에 사용됩니다.

가상계좌 결제의 경우 입금 완료 후에 doorlockKey가 생성됩니다.

예약 진행 취소​

DELETE /reservation

진행 중인 예약을 취소하고 Redis 점유 자원을 해제합니다.

요청 파라미터 없음

PAY_SESSIONID 쿠키 기반으로 점유된 자원을 확인하므로 별도 Request Body가 필요 없습니다. 쿠키가 없거나 만료된 경우에도 200 OK를 반환합니다.

Headers​

이름필수설명
CookieOPAY_SESSIONID

Response​

{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": null
}

결제 취소​

POST /payment/cancel

완료된 결제를 취소(환불)합니다. 로그인 필요.

Headers​

이름필수설명
Content-TypeOapplication/json
CookieO세션 쿠키 (로그인 필요)

Request Body​

파라미터타입필수설명
idLongO결제 ID (나의 결제내역에서 확인)
cancelReasonStringO취소 사유 (최대 200자)
가상계좌 입금 완료 후 취소

가상계좌 입금 완료 건을 취소할 경우 아래 추가 파라미터가 필수입니다:

파라미터타입필수설명
refundReceiveAccountBankStringO환불 은행 코드 (은행 코드 참고)
refundReceiveAccountNumberStringO환불 계좌번호 (최대 20자)
refundReceiveAccountHolderNameStringO예금주 (최대 60자)
카드 결제 취소
{
  "id": 142,
  "cancelReason": "일정 변경"
}
가상계좌 환불
{
  "id": 143,
  "cancelReason": "일정 변경",
  "refundReceiveAccountBank": "88",
  "refundReceiveAccountNumber": "11012345678",
  "refundReceiveAccountHolderName": "홍길동"
}

Response​

{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": null
}
취소 조건
  • 예약 시작 30분 전까지만 취소 가능합니다.
  • 세션의 loginId와 결제자 정보(이메일/휴대폰)가 일치해야 합니다.

나의 결제내역 확인​

GET /my-reservations

로그인한 사용자의 예약/결제 내역을 조회합니다. 로그인 필요.

정보

이 API는 로그인 성공 시 응답으로 반환되는 데이터와 동일한 구조입니다. 이미 로그인된 상태에서 최신 내역을 갱신할 때 사용합니다.

Headers​

이름필수설명
CookieO세션 쿠키 (로그인 필요)

Response​

{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": [
    {
      "id": 142,
      "status": "DONE",
      "method": "카드",
      "branch": "Gwanghwamun",
      "roomNo": "3",
      "startDateTime": "202603051400",
      "endDateTime": "202603051550",
      "amount": 12000,
      "paymentDoneDateTime": "202603051230"
    },
    {
      "id": 143,
      "status": "WAITING_FOR_DEPOSIT",
      "method": "가상계좌",
      "branch": "Yeouido",
      "roomNo": "1",
      "startDateTime": "202603061000",
      "endDateTime": "202603061150",
      "amount": 15000,
      "paymentDoneDateTime": "202603051800",
      "virtualaccountBankName": "신한은행",
      "virtualaccountAccountNumber": "12345678901234",
      "virtualaccountDueDate": "2026-03-06T09:30:00"
    }
  ]
}

data 배열 항목

필드타입Nullable설명
idLongN결제 ID
statusStringNDONE / WAITING_FOR_DEPOSIT / CANCELED
methodStringN카드 / 간편결제 / 가상계좌 / 휴대폰
branchStringN지점 영문명
roomNoStringN방 번호
startDateTimeStringN시작 시간 (YYYYMMDDHHmm)
endDateTimeStringN종료 시간 (YYYYMMDDHHmm)
amountintN결제 금액
paymentDoneDateTimeStringN결제 완료 시간
virtualaccountBankNameStringY가상계좌 은행명
virtualaccountAccountNumberStringY가상계좌 번호
virtualaccountDueDateStringY입금 기한