Agentic Payments

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アカウントとその予約設定を見つけられます。複数ある場合はどれを使うか伝えてください。提供された予約リンクや設定を使う場合は、それをエージェントに渡してください。

エージェントは目的地を解決し、利用可能なホテルを確認し、指定日付の部屋料金を読み込みます。部屋を選んで見積もりを依頼してください。

この支払いフローは現在、1部屋、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クライアントは、部屋情報を直接 arguments に入れて agentic_booking_book を使えます。最初の呼び出しは支払いチャレンジ付きのエラー -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 を使用します。

アプリケーションには支払いに payment.write 権限を持つWinkユーザーアクセストークンが必要です。両方の呼び出しで同じユーザーを使ってください。トークンは Wink-Authorization ヘッダーに入れ、Authorization はウォレットの支払い資格情報用に空けておきます。これらのヘッダーはREST用で、MCPクライアントは独自に認証を処理します。

1. 見積もりをリクエストする

選択した部屋を booking.json として保存し、例の識別子と日付を選択内容に置き換えます。部屋情報はJSON本文に直接入れ、requestラッパーは不要です。

{
  "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は**402 Payment Requiredを返し、WWW-Authenticate: Payment ...チャレンジを各支払い方法ごとに返します。JSON本文には quoteId、amount、currency、expiresAt、methods が含まれます。ここで amount はUSDセントの文字列で、"10000" は$100.00**を意味します。期限内に見積もりを確認してください。まだ支払いは発生していません。

2. 支払いと確定

ウォレットは返されたStripeチャレンジを満たし、Shared Payment Tokenを payload.spt に入れて支払いを行います。チャレンジの支払い詳細を使用してください。

MPP_CREDENTIAL にチャレンジと支払いペイロードを含むウォレットのエンコード済みMPP資格情報を設定し、同じリクエスト本文を同じIDヘッダーで再試行します：

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**を返し、JSON本文に bookingConfirmationCode と 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を添えてサポートに連絡し、別の支払いを開始する前に相談してください。