에이전틱 결제

AI 에이전트를 통해 호텔을 검색하고 객실을 선택하여 예약을 완료할 수 있습니다. 에이전트를 Wink와 결제 지갑에 연결한 후 머무르고 싶은 장소를 알려주세요. Wink는 **Machine Payments Protocol (MPP)**을 사용하여 지갑의 결제를 수락하고 예약 확인을 반환합니다.

1. MCP 서버 연결

전체 예약 흐름을 위해 에이전트에는 Wink Booking Engine과 결제 지갑이 필요합니다.

연결	역할	추가 방법
Wink Booking Engine — 필수	목적지를 찾고, 호텔과 객실 요금을 검색하며, 예약 견적 및 확인, 예약 및 영수증 조회를 수행합니다.	`https://api.wink.travel/mcp/booking-engine`을 원격 HTTP MCP 서버로 추가하세요.
결제 지갑 — 결제 시 필수	구매 승인을 받은 후 결제 자격 증명을 제공합니다.	Stripe Shared Payment Tokens를 지원하는 지갑을 연결하세요. 아래 Link 예시를 참고하세요.
Wink Reference — 선택 사항	국가, 통화 및 기타 참조 데이터를 조회합니다.	`https://api.wink.travel/mcp/reference`
Wink Docs — 선택 사항	에이전트가 문서와 API 계약을 읽는 데 도움을 줍니다.	`https://docs.mcp.wink.travel/mcp`

Booking Engine MCP는 에이전틱 예약 및 결제가 해당 환경에서 활성화된 경우 여행자 예약 흐름에 필요한 도구를 이미 포함하고 있습니다. Wink의 별도 Payment MCP는 원장 및 출금과 같은 금융 작업용이며 객실 결제에는 필요하지 않습니다.

로그인 및 권한 선택

에이전트의 MCP 또는 커넥터 설정을 열고 위의 Booking Engine URL을 추가하세요. Wink Booking과 같은 이름을 지정합니다.
에이전트가 브라우저에서 Wink 로그인 페이지를 엽니다. 예약할 Wink 계정으로 로그인하세요.
동의 화면에서 에이전트가 필요한 권한을 선택하고 연결을 승인합니다.
에이전트로 돌아가면 사용 가능한 도구를 불러오고 이후 MCP 호출에 대한 인증을 관리합니다.

이 흐름에서는 다음 권한을 선택하세요:

권한	필요한 이유
AI 에이전트 접근 (`mcp.read`)	에이전트가 Wink MCP에 연결할 수 있도록 허용합니다.
마케팅 읽기 (`marketing.read`)	에이전트가 계정의 예약 구성(커스터마이제이션)을 찾을 수 있도록 합니다. 계정도 해당 구성에 접근 권한이 있어야 합니다.
결제 쓰기 (`payment.write`)	에이전트가 견적을 결제하고 예약을 확정할 수 있도록 합니다.

연결 시 요청된 로그인 권한을 유지하세요. MCP 클라이언트가 액세스 토큰을 처리하므로 토큰을 채팅에 복사하거나 요청 헤더를 설정할 필요가 없습니다. 필요한 권한을 건너뛰었다면 클라이언트의 로그인 흐름을 통해 다시 연결하고 승인하세요.

결제 지갑 연결

Stripe 결제의 한 가지 옵션은 Link의 에이전트 지갑입니다. 클라이언트가 로컬 MCP 서버를 지원하고 Node.js가 설치되어 있다면 MCP 구성에 다음 항목을 추가하세요:

{
  "mcpServers": {
    "link": {
      "command": "npx",
      "args": ["@stripe/link-cli", "--mcp"]
    }
  }
}

에이전트에게 Link 계정을 연결하도록 요청한 후 제공된 인증 링크를 따라가 연결을 승인하세요. Link는 예약 결제에 사용되는 Shared Payment Token을 제공합니다. 현재 Link는 미국 계정을 지원하므로 예약 전에 지출 한도를 확인하세요. Link 설정 가이드와 MCP 구성을 참고하세요.

에이전트에 이미 호환되는 지갑이 연결되어 있다면 해당 연결을 사용하세요. 지갑 설정과 결제 승인은 Wink 로그인과 별개입니다.

2. 에이전트에게 객실 찾기 요청

예를 들어:

2027년 1월 15일부터 17일까지 방콕에서 성인 2명용 객실을 찾아줘. 선택하기 전에 이용 가능한 옵션, 총 가격, 취소 조건을 보여줘.

에이전트는 접근 가능한 Wink 계정과 예약 구성을 찾을 수 있습니다. 여러 개가 있다면 사용할 계정을 알려주세요. 제공된 예약 링크나 구성을 통해 예약하는 경우 에이전트에 해당 정보를 전달하세요.

에이전트는 목적지를 확인하고, 이용 가능한 호텔을 조회하며, 날짜에 맞는 객실 요금을 불러옵니다. 객실을 선택하고 견적을 요청하세요.

이 결제 흐름은 현재 성인용 USD 가격의 단일 객실만 지원합니다. 견적에는 만료 시간이 있습니다. 견적 요청은 결제나 예약 확정을 의미하지 않습니다.

3. 결제 검토 및 승인

호텔, 객실, 날짜, 투숙객, 취소 조건 및 견적 총액을 확인하세요. 준비가 되면 에이전트에게 예약을 요청하고 지갑에서 요청하는 승인을 완료하세요.

지갑은 견적 결제에 사용할 Stripe Shared Payment Token을 제공합니다.

Tempo 스테이블코인 결제는 곧 지원 예정입니다.

결제가 성공하면 에이전트가 예약 확인 코드를 제공합니다. 또한 Booking Engine MCP를 통해 예약 상세 및 영수증을 조회할 수 있습니다.

결제가 아직 처리 중이거나 응답이 손실된 경우 에이전트가 동일한 결제 시도를 확인하도록 하세요. 견적과 결제 자격 증명을 재사용해야 하며 두 번째 결제를 시작하면 안 됩니다. 결제가 거부되면 새 견적을 요청하고 검토한 후 다시 시도하세요.

에이전트 및 개발자를 위한 도구 참조

아래 모든 Wink 도구는 Booking Engine MCP를 통해 사용할 수 있습니다. MCP 클라이언트는 로그인 시 승인된 권한을 사용해 자동으로 인증을 처리합니다.

단계	도구 및 동작
예약 컨텍스트 선택	`managing_entity_list` 호출 후 선택한 계정에 대해 `customization_get_primary` 또는 `customization_search` 호출. 이미 알려진 커스터마이제이션이 있으면 해당 구성 사용.
목적지 찾기	`destination_lookup_search_suggestions` 및 `destination_lookup_get` 호출.
호텔 및 객실 검색	`inventory_search_city` 또는 `inventory_search_geo` 호출 후 `property_inventory_get`으로 요금 및 이용 가능 여부 조회.
선택한 객실 견적	`agentic_booking_quote` 호출. 객실 정보를 `request` 인수에 전달.
결제 및 확정	연결된 지갑에서 Shared Payment Token을 받아 `agentic_booking_pay` 호출 시 `request.quoteId`와 `request.spt` 전달. 견적과 결제에 동일한 Wink 로그인 사용자 유지.
예약 및 영수증 조회	`booking_search` 또는 `booking_search_list`로 확정된 예약 찾기 후 `booking_get` 및 `booking_receipt_get` 호출.

견적 요청에는 hotelIdentifier, roomRateIdentifier, checkIn, checkOut, adults, children, customizationIdentifier가 필요합니다. 날짜는 YYYY-MM-DD 형식이며 checkOut은 checkIn 이후여야 합니다. adults는 최소 1, children은 0으로 설정하세요.

견적 응답에는 quoteId, amountUsdCents, currency, expiresAt, mppChallenges가 포함됩니다. USD 센트는 달러로 표시하세요: 10000은 $100.00입니다.

결제 결과	다음 단계
`PAYMENT_SUCCEEDED`	`bookingConfirmationCode`와 `chargeReference` 저장.
`IN_PROGRESS`	잠시 기다렸다가 동일한 견적과 자격 증명으로 재시도.
`DECLINED`	새 견적을 요청하고 검토한 후 다시 결제 시도.

성공적인 재시도는 기존 예약을 반환하며 추가 청구하지 않습니다. 타임아웃은 알 수 없는 결과로 간주하고 동일 결제를 재시도하세요. 해결되지 않으면 견적 ID와 함께 지원팀에 문의하세요.

결제 인식 MCP 클라이언트

결제 인식 MCP 클라이언트는 agentic_booking_book을 사용해 객실 필드를 arguments에 직접 전달할 수 있습니다. 첫 호출은 결제 도전과 함께 오류 -32042를 반환합니다. 동일 호출을 지갑 자격 증명(params._meta["org.paymentauth/credential"])과 함께 재시도하면 성공 시 result._meta["org.paymentauth/receipt"]가 포함됩니다. 오류 -32043은 결제 실패 및 도전을 포함하며, 확정 거부는 새 견적이 필요하고, 불완전한 결제 페이로드는 동일 도전으로 재시도할 수 있습니다. -32603 오류에서 data.failure.reason이 payment-in-progress 또는 already-consumed이면 동일 자격 증명으로 재시도하세요; 오류 코드만으로는 충분하지 않습니다.

REST를 통한 예약

Wink에 직접 HTTP로 호출하는 통합을 구축할 때 REST를 사용하세요. 견적과 결제 모두 **POST https://api.wink.travel/api/mpp/booking**를 사용합니다.

애플리케이션에는 결제 권한이 있는 Wink 사용자 액세스 토큰이 필요합니다. 두 호출에 동일한 사용자를 유지하세요. 토큰은 Wink-Authorization 헤더에 보내고, Authorization 헤더는 지갑 결제 자격 증명용으로 남겨둡니다. 이 헤더는 REST에 적용되며 MCP 클라이언트는 자체 인증을 처리합니다.

1. 견적 요청

선택한 객실을 booking.json으로 저장하고 예시 식별자와 날짜를 선택한 값으로 바꾸세요. 객실 필드는 request 래퍼 없이 JSON 본문에 직접 들어갑니다.

{
  "hotelIdentifier": "YOUR_HOTEL_ID",
  "roomRateIdentifier": "YOUR_ROOM_RATE_ID",
  "checkIn": "2027-01-15",
  "checkOut": "2027-01-17",
  "adults": 2,
  "children": 0,
  "customizationIdentifier": "YOUR_CUSTOMIZATION_ID"
}

WINK_ACCESS_TOKEN을 사용자 액세스 토큰으로 설정하고 요청을 전송하세요:

curl -i https://api.wink.travel/api/mpp/booking \
  -H "Wink-Authorization: Bearer $WINK_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @booking.json

Wink는 각 결제 수단에 대해 WWW-Authenticate: Payment ... 도전과 함께 **402 Payment Required**를 반환합니다. JSON 본문에는 quoteId, amount, currency, expiresAt, methods가 포함됩니다. 여기서 amount는 USD 센트 문자열이며 "10000"은 $100.00입니다. 만료 전에 견적을 검토하세요; 아직 결제는 이루어지지 않았습니다.

2. 결제 및 확정

지갑이 반환된 Stripe 도전을 이행하여 payload.spt에 Shared Payment Token을 제공하도록 하세요. 도전에서 결제 세부 정보를 사용합니다.

MPP_CREDENTIAL을 도전과 결제 페이로드를 포함하는 지갑의 인코딩된 MPP 자격 증명으로 설정하세요. 동일한 요청 본문을 재시도하며 신원 헤더를 유지합니다:

curl -i https://api.wink.travel/api/mpp/booking \
  -H "Wink-Authorization: Bearer $WINK_ACCESS_TOKEN" \
  -H "Authorization: Payment $MPP_CREDENTIAL" \
  -H 'Content-Type: application/json' \
  --data-binary @booking.json

성공 시 Wink는 **200 OK**와 bookingConfirmationCode가 포함된 JSON 본문, Payment-Receipt 헤더를 반환합니다. 확인 코드와 영수증을 저장하세요. 성공적인 재시도는 기존 예약을 반환하며 추가 청구하지 않습니다.

응답 및 재시도 처리

응답	처리 방법
`400`	잘못된 객실 정보 또는 잘못된 자격 증명을 수정하세요.
`401` / `403`	사용자 인증 및 결제 권한을 확인하세요.
`402`	반환된 문제와 도전을 검사하세요. 확정 결제 거부는 새 견적이 필요하며, 불완전한 결제 페이로드는 원래 도전을 재사용합니다. 결제 전에 가격을 검토하세요.
`409`	결제 결과가 미확정 상태입니다. 잠시 기다렸다가 동일한 본문과 자격 증명으로 예약 엔드포인트를 재시도하세요.
`429`	`Retry-After`에 명시된 초만큼 기다린 후 재시도하세요.

409 응답은 application/problem+json 본문을 포함하며, type을 다음 정확한 URL과 비교하세요:

문제 유형	의미
https://api.wink.travel/problems/payment-in-progress	결제 시도가 아직 진행 중이거나 정산이 아직 확인되지 않았습니다.
https://api.wink.travel/problems/already-consumed	도전 또는 결제 증명이 이미 성공했을 수 있는 시도에서 사용되었습니다. 이 자체로 예약 확정을 의미하지 않습니다.

두 경우 모두 동일한 결제를 재시도하고 새 견적 결제는 하지 마세요. URL은 문제를 식별하고 문서화하며 결제 또는 폴링 엔드포인트가 아닙니다. POST /api/mpp/booking을 재시도하고, 자유 텍스트 detail 대신 문제 type을 사용해 처리 방법을 결정하세요. 모든 Wink 결제 문제는 문제 유형 참조를 참고하세요.

결제 제출 후 타임아웃, 응답 손실 또는 서버 오류도 결과를 알 수 없게 만들 수 있습니다. 동일한 결제 요청을 재시도하세요. 결과가 계속 미확정이면 새 결제를 시작하기 전에 견적 ID와 함께 지원팀에 문의하세요.