Rail Connect 연동 가이드

Authorization: Bearer <API_KEY>

Authorization: Bearer <API_KEY>
X-Timestamp: 1755100800
X-Signature: sha256=<hex>

POST
/api/booking/reserve
1755100800
<본문을 sha256 한 16진수>

POST https://rail-connect.rideus.net/api/booking/reserve
Authorization: Bearer <API_KEY>
Content-Type: application/json; charset=utf-8
X-Timestamp: <유닉스 초>
X-Signature: sha256=<hex>

{ "ok": true, "currency": "USD", "fxRate": 1380.0, "fxAt": 1755500000,
  "fxMarketRate": 1380.0, "fxSpread": 2.0,
  "trains": [ { "trainNo": "101",
    "generalFare": 59800, "ticketFee": 5980, "customerTotal": 65780,
    // 원화 값을 그대로 환산한 것. 짝이 같으므로 고르는 기준도 같습니다 —
    // 화면에 쓸 값은 customerTotal 입니다(generalFare 는 수수료가 빠져 있습니다)
    "usd": { "generalFare": 43.33, "firstSurcharge": 17.32,
             "ticketFee": 4.33, "customerTotal": 47.67 } } ] }

fxRate = fxMarketRate ÷ (1 + fxSpread/100)
원화   = chargeAmount × fxRate          ← 정산 대조는 이 식으로

{
  "live": true,
  "authorizations": [ … ],
  "sweepStale": true,
  "heldRsvIds": ["…", "…"],
  "sweepStaleMinutes": 10
}

{ "customerKey": "member-12345",
  "status": "paid",        // (선택) reserved | cancelled | expired | paid | refunded | failed
  "includeUnpaid": false,  // (선택) 결제 전 선점까지 볼지 — 기본 false
  "limit": 50 }            // (선택) 기본 50, 최대 200

"paxFares": {
  "exact": true, "source": "carrier",
  "rows": [
    { "label": "어른1", "type": "adults", "seat": "5호차 6A",
      "netPay": 7500,        // 결제운임 (철도사 운임)
      "discountRate": null,  // 할인율 — 할인이 걸린 좌석에만
      "fee": 750,            // 발권수수료
      "subtotal": 8250 },    // 소계 = netPay + fee
    { "label": "어른2", "type": "adults", "seat": "5호차 6B",
      "netPay": 7500, "discountRate": null, "fee": 750, "subtotal": 8250 } ],
  "totals": { "netPay": 15000, "fee": 1500, "subtotal": 16500 } }

{ "booking": {
    "seats": [
      { "carNo": "10", "seatNo": "11A",
        "qrImageUrl": "https://…/qr/{파트너}/{예약번호}/0/{서명}.png" },
      { "carNo": "10", "seatNo": "11B",
        "qrImageUrl": "https://…/qr/{파트너}/{예약번호}/1/{서명}.png" }
    ],
    "seatClass": "standard",          // standard(일반실) | first(특실) · 모르면 없음
    "qrImageUrl": "https://…/qr/{파트너}/{예약번호}/{서명}.png" } }

{ "email": "gildong@example.com" }                 // 이메일로
{ "phone": "010-1234-5678" }                       // 전화번호로
{ "email": "…", "lastName": "홍", "firstName": "길동" }  // 이름으로 더 좁히기

{ "ok": true, "stage": "listed", "count": 2, "truncated": false,
  "customerKey": "member-12345",
  "matchedBy": "customerKey",        // customerKey | booker (이메일·전화로 찾음)
  "includeUnpaid": false,            // 결제 전 선점을 포함해 받은 목록인지
  "bookings": [
    { "rsvId": "…", "orderRef": "…", "status": "paid",
      "service": "코레일", "train": "KTX 101",
      "depName": "서울", "arrName": "부산",
      "depDate": "20260910", "depTime": "090000", "arrTime": "094500",
      "passengers": 2, "paxBreakdown": { "adults": 2 },
      "fare": 40400, "ticketFee": 4040, "customerTotal": 44440,
      "refundAmount": null, "approvalNo": "…",
      "paidAt": "…", "refundedAt": null, "createdAt": "…" }
  ] }

{ "rsvId": "…" }

{ "ok": true, "stage": "found",
  "booking": {
    "rsvId": "…", "status": "refunded", "train": "KTX 101",
    "depName": "서울", "arrName": "부산", "depAt": "…",
    // 인원 수만큼 옵니다 — 2인 예약이면 2개. price 는 **철도사 운임**이라
    // 발권수수료가 빠져 있습니다(수수료까지 더한 값은 paxFares 의 subtotal).
    // price·paxType·discountName 은
    // 철도사가 인원별로 준 값이라, 못 얻었으면 그 키가 빠집니다.
    "seats": [ { "carNo": "3", "seatNo": "5A", "price": 22400, "paxType": "어른" },
               { "carNo": "3", "seatNo": "5B", "price": 11200, "paxType": "어린이",
                 "discountName": "다자녀행복" } ],
    "booker": { "customerKey": "member-12345", "lastName": "홍", "firstName": "길동",
                "email": "…", "phone": "…", "phoneCountry": "+82", "country": "KR" },
    "fareBreakdown": { "listFare": 53900, "discount": 13500, "discountRate": 25.0,
                       "fare": 40400, "ticketFee": 4040, "ticketFeeRate": 10.0,
                       "customerTotal": 44440 },
    "payMethod": "신한카드 5432-****-****-1234", "payApprovalNo": "16004215",
    "refund": { "carrierFee": 2020, "cancelFee": 2020, "cancelFeeRate": 5.0,
                "cancelBand": "평일 · 출발 3시간 전~출발 직전",
                "refundAmount": 42210, "refundedAt": "…",
                "ticketFeeRefunded": true } } }   // 청구액에 포함돼 함께 환불됨

// availability — 열차마다. 1인 일반실(generalFare) 기준이라 확정 금액이 아님
{ "ticketFeeRate": 10.0, "feeBasis": "1인 일반실 기준 — 확정 금액은 reserve 응답을 쓸 것",
  "trains": [ { "generalFare": 47400, "ticketFee": 4740, "customerTotal": 52140 } ] }

// reserve — 예약 총액(reservation.price) 기준. **고객에게 청구할 확정 금액**
{ "ok": true, "reservation": { "price": 40400 },
  "ticketFeeRate": 10.0, "ticketFee": 4040, "customerTotal": 44440 }

// pay — 건별 + 합계. 금액이 확정된 건(paid·dry-run)만 계산에 넣음
{ "results": [ { "amount": 40400, "ticketFee": 4040, "customerTotal": 44440 } ],
  "ticketFeeTotal": 4040, "customerTotal": 44440 }

// cancel 응답의 refund.applied — 반환 시점에 실제로 적용한 값
{ "refund": { "amount": 38380, "fee": 2020,          // 철도사 반환액·위약금(실제값)
              "applied": { "fare": 40400,
                           "charged": 44440,          // 고객 청구액
                           "carrierFee": 2020,        // 환불액에서 빼지 않음
                           "cancelFee": 2230, "cancelFeeRate": 5.0,
                           "cancelFeeBase": 44440,    // 요율 기준 = 청구액
                           "cancelBand": "평일 · 출발 3시간 전~출발 직전",
                           "refundAmount": 42210,     // = charged − cancelFee
                           "ticketFeePaid": 4040,     // 청구액에 포함돼 함께 돌아감
                           // 요율을 어디서 가져왔나: partner(키 설정) | default(규정) | none
                           "rateSource": "partner" } } }

methods            결제수단 목록 (파트너) — checkout 에 넣을 이름의 출처
  → reserve        좌석 선점 (파트너)
  → checkout       결제 주소 발급 (파트너) — payUrl 을 고객에게
  → 고객 결제      payUrl 로 보내면 포트원 결제창이 바로 뜹니다
  → 포트원 웹훅    저희가 포트원에 재조회 + 금액 대조 후 **여기서 결제 확정**
  → 철도사 발권    저희가 처리(뒤에서 실행) → ticket.issued 웹훅
  → redirect_url   고객 브라우저를 파트너 사이트로 복귀

cancel             표 반환 + 고객 환불(포트원)까지 저희가 처리

{ "ok": false, "code": "SOLD_OUT", "stage": "reserve",
  "error": "매진되었습니다" }

POST <웹훅 URL>
Content-Type: application/json; charset=utf-8
X-Korail-Event: payment.paid
X-Korail-Signature: sha256=<hex>

{ "event": "payment.paid", "tenantId": "…", "apiKeyId": "…",
  "data": { "rsvId": "…", "orderRef": "…", "amount": 59800, "approvalNo": "…" } }

OPTIONS /api/booking/availability      → 204 (등록된 오리진) / 403
POST    /api/booking/availability      → 응답에 Access-Control-Allow-Origin 포함

Origin 헤더가 없는 서버 간 호출은 이 검사를 거치지 않습니다.

access-control-allow-headers:
  Authorization, Content-Type, X-Api-Key, X-Timestamp, X-Signature

secret   = sha256(API_KEY).hexdigest()
expected = "sha256=" + hmac_sha256(secret, request_body).hexdigest()