Платежи через агента
Вы можете искать отель, выбирать номер и завершать бронирование через вашего AI-агента. Подключите его к Wink и платежному кошельку, затем скажите, где хотите остановиться. Wink использует Machine Payments Protocol (MPP) для принятия платежа из кошелька и возврата подтверждения бронирования.
1. Подключите MCP-серверы
Заголовок раздела «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 уже включает инструменты, необходимые для процесса бронирования путешественником, когда агентское бронирование и оплата включены для этой среды. Отдельный Payment MCP от Wink предназначен для финансовых операций, таких как бухгалтерские книги и вывод средств; он не нужен для оплаты номера.
Войдите в систему и выберите разрешения
Заголовок раздела «Войдите в систему и выберите разрешения»- Откройте настройки MCP или коннектора вашего агента и добавьте URL Booking Engine выше. Дайте ему имя, например 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. Попросите агента найти номер
Заголовок раздела «2. Попросите агента найти номер»Например:
Найди номер в Бангкоке для двух взрослых с 15 по 17 января 2027 года. Покажи доступные варианты, общую цену и условия отмены перед выбором.
Ваш агент может найти доступные аккаунты Wink и их конфигурации бронирования. Если у вас несколько, скажите, какой использовать. Если вы бронируете через предоставленную ссылку или конфигурацию, передайте её агенту.
Агент затем определит направление, проверит доступные отели и загрузит цены на номера на ваши даты. Выберите номер и запросите квоту.
Этот платежный процесс в настоящее время поддерживает один номер, с ценой в USD, только для взрослых. Квота имеет срок действия. Запрос квоты не списывает деньги и не подтверждает бронирование.
3. Проверьте и подтвердите оплату
Заголовок раздела «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-клиенты с поддержкой оплаты»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
Заголовок раздела «Бронирование через REST»Используйте REST при создании интеграции, которая вызывает Wink напрямую по HTTP. И квота, и оплата используют POST https://api.wink.travel/api/mpp/booking.
Вашему приложению нужен токен доступа пользователя Wink с разрешением payment.write для оплаты. Используйте того же пользователя для обоих вызовов. Отправляйте токен в заголовке Wink-Authorization, оставляя Authorization для платежных данных кошелька. Эти заголовки применимы к REST; MCP-клиент обрабатывает аутентификацию самостоятельно.
1. Запрос квоты
Заголовок раздела «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.jsonWink возвращает 402 Payment Required с вызовом WWW-Authenticate: Payment ... для каждого предложенного метода. Тело JSON содержит quoteId, amount, currency, expiresAt и methods. Здесь amount — строка в центах USD: "10000" означает 100,00 $. Проверьте квоту до её истечения; оплата ещё не списана.
2. Оплата и подтверждение
Заголовок раздела «2. Оплата и подтверждение»Пусть кошелек выполнит возвращённый вызов Stripe, предоставив Shared Payment Token в payload.spt. Используйте платежные данные из вызова.
Установите 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, 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, чтобы решить, что делать. См. справочник по типам проблем для всех проблем оплаты Wink.
Таймаут, потерянный ответ или ошибка сервера после отправки оплаты также могут оставить результат неизвестным. Повторите тот же платежный запрос. Если результат остаётся неразрешённым, обратитесь в поддержку с ID квоты перед началом новой оплаты.