Pagos Agentic

Puedes buscar un hotel, elegir una habitación y completar tu reserva a través de tu agente de IA. Conéctalo a Wink y a una billetera de pago, luego indícale dónde quieres alojarte. Wink utiliza el Machine Payments Protocol (MPP) para aceptar el pago de la billetera y devolver la confirmación de tu reserva.

1. Conecta los servidores MCP

Para el flujo completo de reserva, tu agente necesita el Wink Booking Engine y una billetera de pago.

Conexión	Qué hace	Cómo agregarla
Wink Booking Engine — requerido	Encuentra destinos, busca hoteles y tarifas de habitaciones, cotiza y confirma reservas, y recupera tus reservas y recibos.	Agrega https://api.wink.travel/mcp/booking-engine como un servidor MCP HTTP remoto.
Billetera de pago — requerida para pagar	Proporciona credenciales de pago después de que apruebes la compra.	Conecta una billetera que soporte Stripe Shared Payment Tokens. Consulta el ejemplo de Link más abajo.
Wink Reference — opcional	Consulta países, monedas y otros datos de referencia.	https://api.wink.travel/mcp/reference
Wink Docs — opcional	Ayuda a tu agente a leer documentación y contratos API.	https://docs.mcp.wink.travel/mcp

El Booking Engine MCP ya incluye las herramientas necesarias para el flujo de reserva del viajero, cuando la reserva y el pago agentic están habilitados para ese entorno. El Payment MCP separado de Wink es para operaciones financieras como libros contables y retiros; no es necesario para pagar una habitación.

Inicia sesión y elige permisos

1. Abre la configuración MCP o del conector de tu agente y agrega la URL del Booking Engine mencionada arriba. Asígnale un nombre como Wink Booking.
2. Tu agente abre la página de inicio de sesión de Wink en tu navegador. Inicia sesión con la cuenta de Wink bajo la cual quieres reservar.
3. En la pantalla de consentimiento, elige los permisos que tu agente necesita y aprueba la conexión.
4. Regresa a tu agente. Este carga las herramientas disponibles y gestiona la autenticación para las llamadas MCP posteriores.

Para este flujo, selecciona:

Permiso	Por qué es necesario
Acceso de agente IA (mcp.read)	Permite que tu agente se conecte a Wink MCP.
Lectura de marketing (marketing.read)	Permite que el agente encuentre la configuración de reserva de tu cuenta, llamada personalización. Tu cuenta también debe tener acceso a esa configuración.
Escritura de pago (payment.write)	Permite que el agente pague la cotización y confirme la reserva.

Mantén los permisos de inicio de sesión solicitados por la conexión. Tu cliente MCP maneja los tokens de acceso; no necesitas copiar un token en el chat ni configurar encabezados de solicitud. Si omitiste un permiso necesario, vuelve a conectar mediante el flujo de inicio de sesión de tu cliente y apruébalo.

Conecta una billetera de pago

Para pagos con Stripe, una opción es la billetera de agente de Link. Si tu cliente soporta servidores MCP locales y tienes Node.js instalado, agrega esta entrada a su configuración MCP:

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

Pide a tu agente que conecte tu cuenta Link, luego sigue el enlace de verificación que proporciona y aprueba la conexión. Link suministra el Shared Payment Token usado para pagar la reserva. Actualmente Link soporta cuentas de EE. UU.; verifica sus límites de gasto antes de reservar. Consulta la guía de configuración de Link y la configuración MCP.

Si tu agente ya tiene una billetera compatible conectada, usa esa conexión. La configuración de la billetera y la aprobación del pago son independientes del inicio de sesión en Wink.

2. Pide a tu agente que busque una habitación

Por ejemplo:

Busca una habitación en Bangkok para dos adultos del 15 al 17 de enero de 2027. Muéstrame las opciones disponibles, el precio total y las condiciones de cancelación antes de que elija.

Tu agente puede encontrar las cuentas Wink accesibles y sus configuraciones de reserva. Si tienes varias, indícale cuál usar. Si reservas mediante un enlace o configuración de reserva proporcionada, dáselo al agente en su lugar.

El agente resuelve tu destino, verifica hoteles disponibles y carga tarifas de habitaciones para tus fechas. Elige una habitación y pide una cotización.

Este flujo de pago soporta actualmente una habitación, con precio en USD, solo para adultos. Una cotización tiene un tiempo de expiración. Solicitar una no te cobra ni confirma una reserva.

3. Revisa y aprueba el pago

Verifica el hotel, habitación, fechas, huéspedes, condiciones de cancelación y total cotizado. Cuando estés listo, pide a tu agente que reserve y complete cualquier aprobación solicitada por tu billetera.

La billetera proporciona un Stripe Shared Payment Token para pagar la cotización.

Los pagos con stablecoin Tempo estarán disponibles pronto.

Después de que el pago sea exitoso, tu agente te da un código de confirmación de reserva. También puede recuperar los detalles de la reserva y el recibo a través del Booking Engine MCP.

Si el pago aún está en proceso o se pierde la respuesta, deja que el agente verifique el mismo intento de pago. Debe reutilizar la cotización y la credencial de pago en lugar de iniciar un segundo pago. Si el pago es rechazado, pide una cotización nueva y revísala antes de intentar de nuevo.

Referencia de herramientas para agentes y desarrolladores

Todas las herramientas de Wink a continuación están disponibles a través del Booking Engine MCP. El cliente MCP envía la autenticación automáticamente usando los permisos aprobados durante el inicio de sesión.

Paso	Herramientas y comportamiento
Seleccionar contexto de reserva	managing_entity_list, luego customization_get_primary o customization_search para la cuenta seleccionada. Usa una personalización suministrada cuando ya se conozca una.
Buscar un destino	destination_lookup_search_suggestions y destination_lookup_get.
Buscar hoteles y habitaciones	inventory_search_city o inventory_search_geo, luego property_inventory_get para tarifas y disponibilidad.
Cotizar la habitación seleccionada	agentic_booking_quote. Pasa los detalles de la habitación dentro de su argumento request.
Pagar y confirmar	Obtén un Shared Payment Token de la billetera conectada, luego llama a agentic_booking_pay con request.quoteId y request.spt. Mantén el mismo usuario Wink conectado para cotización y pago.
Recuperar la reserva y recibo	Usa booking_search o booking_search_list para encontrar la reserva confirmada, luego booking_get y booking_receipt_get con su identificador de reserva.

La solicitud de cotización necesita hotelIdentifier, roomRateIdentifier, checkIn, checkOut, adults, children y customizationIdentifier. Las fechas usan YYYY-MM-DD; checkOut debe ser posterior a checkIn. Establece adults al menos en 1 y children en 0.

La cotización devuelve quoteId, amountUsdCents, currency, expiresAt y mppChallenges. Muestra los centavos USD como dólares: 10000 significa $100.00.

Resultado del pago	Siguiente paso
PAYMENT_SUCCEEDED	Guarda bookingConfirmationCode y chargeReference.
IN_PROGRESS	Espera brevemente y reintenta la misma cotización y credencial.
DECLINED	Solicita una cotización nueva y revísala antes de otro pago.

Un reintento exitoso devuelve la reserva existente sin cobrar de nuevo. Trata un tiempo de espera como un resultado desconocido y reintenta el mismo pago. Si sigue sin resolverse, contacta soporte con el ID de cotización.

Clientes MCP conscientes de pagos

Los clientes MCP conscientes de pagos pueden usar agentic_booking_book con los campos de habitación directamente en arguments. La primera llamada devuelve error -32042 con desafíos de pago. Reintenta la misma llamada con la credencial de billetera en params._meta["org.paymentauth/credential"]; el éxito incluye result._meta["org.paymentauth/receipt"]. El error -32043 indica un fallo de pago y desafío: un rechazo definitivo necesita una cotización nueva, mientras que una carga de pago incompleta puede reintentar con el mismo desafío. Para -32603, un data.failure.reason de payment-in-progress o already-consumed significa reintentar la misma credencial; el código de error solo no es suficiente.

Reserva mediante REST

Usa REST cuando construyas una integración que llame a Wink directamente por HTTP. Tanto la cotización como el pago usan POST https://api.wink.travel/api/mpp/booking.

Tu aplicación necesita un token de acceso de usuario Wink con permiso payment.write para pagar. Mantén el mismo usuario para ambas llamadas. Envía el token en Wink-Authorization, dejando Authorization disponible para la credencial de pago de la billetera. Estos encabezados aplican para REST; un cliente MCP maneja su propia autenticación.

1. Solicita una cotización

Guarda la habitación seleccionada como booking.json, reemplazando los identificadores y fechas de ejemplo con tu selección. Los campos de la habitación van directamente en el cuerpo JSON, sin un envoltorio 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"
}

Establece WINK_ACCESS_TOKEN con el token de acceso del usuario y envía la solicitud:

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 devuelve 402 Payment Required con un desafío WWW-Authenticate: Payment ... para cada método ofrecido. El cuerpo JSON incluye quoteId, amount, currency, expiresAt y methods. Aquí, amount es una cadena en centavos USD: "10000" significa $100.00. Revisa la cotización antes de su expiración; aún no se ha cobrado ningún pago.

2. Paga y confirma

Haz que la billetera cumpla el desafío Stripe devuelto suministrando un Shared Payment Token en payload.spt. Usa los detalles de pago de ese desafío.

Establece MPP_CREDENTIAL con la credencial MPP codificada de la billetera, que contiene el desafío y la carga de pago. Reintenta el mismo cuerpo de solicitud, manteniendo el encabezado de identidad:

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

En caso de éxito, Wink devuelve 200 OK, un cuerpo JSON con bookingConfirmationCode y un encabezado Payment-Receipt. Guarda la confirmación y el recibo. Un reintento exitoso devuelve la reserva existente sin cobrar de nuevo.

Maneja respuestas y reintentos

Respuesta	Qué hacer
400	Corrige detalles inválidos de la habitación o una credencial malformada.
401 / 403	Verifica la autenticación del usuario y el permiso de pago.
402	Inspecciona el problema y desafío devueltos. Un rechazo definitivo de pago obtiene una cotización nueva; una carga de pago incompleta reutiliza el desafío original. Revisa el precio antes de pagar.
409	El resultado del pago está sin resolver. Espera brevemente y reintenta el mismo cuerpo y credencial en el endpoint de reserva.
429	Espera el número de segundos indicado en Retry-After, luego reintenta.

Una respuesta 409 tiene un cuerpo application/problem+json. Compara su type con estas URLs exactas:

Tipo de problema	Significado
https://api.wink.travel/problems/payment-in-progress	Un intento de pago aún está en curso o el asentamiento no puede confirmarse todavía.
https://api.wink.travel/problems/already-consumed	El desafío o prueba de pago ya fue usado por un intento posiblemente exitoso. Esto por sí solo no confirma la reserva.

Ambos significan reintenta el mismo pago; no pagues una cotización nueva. Las URLs identifican y documentan el problema; no son endpoints de pago o sondeo. Reintenta POST /api/mpp/booking y usa el type del problema en lugar del texto libre detail para decidir qué hacer. Consulta la referencia de tipos de problema para todos los problemas de pago de Wink.

Un tiempo de espera, respuesta perdida o error de servidor tras enviar el pago también puede dejar el resultado desconocido. Reintenta la misma solicitud de pago. Si el resultado sigue sin resolverse, contacta soporte con el ID de cotización antes de iniciar otro pago.