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 вже включає інструменти, необхідні для процесу бронювання мандрівника, коли агентське бронювання та оплата увімкнені для цього середовища. Окремий Payment MCP від Wink призначений для фінансових операцій, таких як бухгалтерські книги та виведення коштів; він не потрібен для оплати номера.

Увійдіть і виберіть дозволи

1. Відкрийте налаштування MCP або конектора вашого агента і додайте URL Booking Engine, наведений вище. Дайте йому ім’я, наприклад Wink Booking.
2. Ваш агент відкриває сторінку входу Wink у браузері. Увійдіть за обліковим записом Wink, під яким хочете бронювати.
3. На екрані згоди виберіть дозволи, які потрібні вашому агенту, і підтвердіть підключення.
4. Поверніться до агента. Він завантажить доступні інструменти та керуватиме автентифікацією для наступних викликів 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. Попросіть агента знайти номер

Наприклад:

Знайди номер у Бангкоку для двох дорослих з 15 по 17 січня 2027 року. Покажи доступні варіанти, загальну ціну та умови скасування перед вибором.

Ваш агент може знайти доступні облікові записи Wink і їхні конфігурації бронювання. Якщо їх кілька, скажіть, який використовувати. Якщо ви бронюєте через надане посилання або конфігурацію, передайте це агенту.

Агент визначить ваше місце призначення, перевірить доступні готелі та завантажить тарифи на номери для ваших дат. Оберіть номер і попросіть пропозицію.

Цей процес оплати наразі підтримує один номер, ціною в USD, лише для дорослих. Пропозиція має термін дії. Запит пропозиції не стягує оплату і не підтверджує бронювання.

3. Перевірте і підтвердіть оплату

Перевірте готель, номер, дати, гостей, умови скасування та загальну суму пропозиції. Коли будете готові, попросіть агента забронювати і завершити будь-яке підтвердження, яке запитує ваш гаманець.

Гаманець надає Stripe Shared Payment Token для оплати пропозиції.

Платежі Tempo stablecoin скоро з’являться.

Після успішної оплати агент надасть вам код підтвердження бронювання. Він також може отримати деталі бронювання та чек через 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

Використовуйте REST для інтеграції, яка викликає Wink безпосередньо через HTTP. І пропозиція, і оплата використовують POST https://api.wink.travel/api/mpp/booking.

Вашому додатку потрібен токен доступу користувача Wink з дозволом payment.write для оплати. Використовуйте того самого користувача для обох викликів. Надсилайте токен у заголовку 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 реквізит гаманця, який містить виклик і платіжний пакет. Повторіть той самий запит, зберігаючи заголовок ідентичності:

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 пропозиції перед початком іншої оплати.