תשלומים סוכניים

אתם יכולים לחפש מלון, לבחור חדר ולהשלים את ההזמנה דרך הסוכן המבוסס בינה מלאכותית שלכם. חברו אותו ל-Wink ולארנק תשלום, ואז אמרו לו היכן תרצו לשהות. Wink משתמש בפרוטוקול תשלומים למכונה (MPP) כדי לקבל את התשלום מהארנק ולהחזיר את אישור ההזמנה שלכם.

1. חברו את שרתי MCP

לזרימת ההזמנה המלאה, הסוכן שלכם זקוק למנוע ההזמנות של Wink וארנק תשלום.

חיבור	מה הוא עושה	איך להוסיף אותו
מנוע ההזמנות של Wink — חובה	מוצא יעדים, מחפש מלונות ומחירי חדרים, מציע ומאשר הזמנות, ומחזיר את ההזמנות והקבלות שלכם.	הוסיפו את `https://api.wink.travel/mcp/booking-engine` כשרת MCP מרוחק מסוג HTTP.
ארנק תשלום — חובה לתשלום	מספק אישורי תשלום לאחר שאתם מאשרים את הרכישה.	חברו ארנק התומך ב-Stripe Shared Payment Tokens. ראו את דוגמת Link למטה.
הפניה ל-Wink — אופציונלי	מחפש מדינות, מטבעות ונתוני הפניה נוספים.	`https://api.wink.travel/mcp/reference`
מסמכי Wink — אופציונלי	עוזר לסוכן שלכם לקרוא תיעוד וחוזי API.	`https://docs.mcp.wink.travel/mcp`

מנוע ההזמנות MCP כבר כולל את הכלים הדרושים לזרימת הזמנות למטייל, כאשר הזמנה ותשלום סוכניים מופעלים בסביבה זו. MCP התשלום הנפרד של Wink מיועד לפעולות פיננסיות כגון ספרי חשבונות ומשיכות; הוא אינו נדרש לתשלום עבור חדר.

התחברו ובחרו הרשאות

פתחו את הגדרות MCP או המחבר של הסוכן שלכם והוסיפו את כתובת מנוע ההזמנות שצוינה למעלה. תנו לו שם כמו Wink Booking.
הסוכן שלכם פותח את דף ההתחברות של Wink בדפדפן שלכם. התחברו עם חשבון Wink שברצונכם להזמין תחתיו.
במסך ההסכמה, בחרו את ההרשאות שהסוכן שלכם צריך, ואז אשרו את החיבור.
חזרו לסוכן שלכם. הוא טוען את הכלים הזמינים ומנהל אימות לקריאות MCP הבאות.

לזרימה זו, בחרו:

הרשאה	למה היא נדרשת
גישה לסוכן בינה מלאכותית (`mcp.read`)	מאפשרת לסוכן שלכם להתחבר ל-MCP של Wink.
קריאת שיווק (`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 שאליהם יש לכם גישה ואת תצורות ההזמנה שלהם. אם יש לכם כמה, אמרו לו איזה להשתמש. אם אתם מזמינים דרך קישור הזמנה או תצורה שסופקו, תנו זאת לסוכן במקום.

הסוכן יפתור את היעד שלכם, יבדוק מלונות זמינים ויטען מחירי חדרים לתאריכים שלכם. בחרו חדר ובקשו הצעת מחיר.

זרימת תשלום זו תומכת כרגע בחדר אחד, במחיר בדולרים אמריקאיים, למבוגרים בלבד. להצעה יש תוקף. בקשת הצעה אינה מחייבת תשלום או מאשרת הזמנה.

3. בדקו ואשרו תשלום

בדקו את המלון, החדר, התאריכים, האורחים, תנאי הביטול והסכום הכולל שהוצע. כשתהיו מוכנים, בקשו מהסוכן להזמין ולהשלים כל אישור שנדרש על ידי הארנק שלכם.

הארנק מספק Stripe Shared Payment Token לתשלום עבור ההצעה.

תשלומי מטבע יציב Tempo יגיעו בקרוב.

לאחר שהתשלום מצליח, הסוכן שלכם נותן לכם קוד אישור הזמנה. הוא יכול גם לשלוף את פרטי ההזמנה והקבלה דרך מנוע ההזמנות MCP.

אם התשלום עדיין בעיבוד או שהתגובה אבודה, אפשרו לסוכן לבדוק את ניסיון התשלום אותו. עליו להשתמש מחדש בהצעה ובאישור התשלום במקום להתחיל תשלום שני. אם התשלום נדחה, בקשו הצעה חדשה ובחנו אותה לפני ניסיון נוסף.

הפניה לכלים לסוכנים ומפתחים

כל כלי Wink למטה זמין דרך מנוע ההזמנות 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. הציגו סנטים בדולרים אמריקאיים כדולרים: 10000 פירושו $100.00.

תוצאת תשלום	שלב הבא
`PAYMENT_SUCCEEDED`	שמרו את `bookingConfirmationCode` ו-`chargeReference`.
`IN_PROGRESS`	המתינו מעט ונסו שוב את אותה הצעה ואישור.
`DECLINED`	בקשו הצעה חדשה ובחנו אותה לפני תשלום נוסף.

ניסיון חוזר מוצלח מחזיר את ההזמנה הקיימת ללא חיוב נוסף. התייחסו לפיגור זמן כאל תוצאה לא ידועה ונסו שוב את אותו תשלום. אם הבעיה נמשכת, פנו לתמיכה עם מזהה ההצעה.

לקוחות 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 הוא מחרוזת בסנטים בדולרים אמריקאיים: "10000" פירושו $100.00. בדקו את ההצעה לפני שפג תוקפה; עדיין לא בוצע תשלום.

2. שלמו ואשרו

הארנק ממלא את אתגר Stripe שהוחזר על ידי אספקת Shared Payment Token ב-payload.spt. השתמשו בפרטי התשלום מהאתגר.

הגדירו MPP_CREDENTIAL לאישור MCP המקודד של הארנק, המכיל את האתגר ונתוני התשלום. נסו שוב את אותו גוף בקשה, תוך שמירת כותרת הזהות:

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 לכתובות המדויקות הבאות:

סוג הבעיה	משמעות
https://api.wink.travel/problems/payment-in-progress	ניסיון תשלום עדיין מתבצע או שלא ניתן לאשר את הסגירה.
https://api.wink.travel/problems/already-consumed	האתגר או הוכחת התשלום כבר נוצלו בניסיון שעשוי להיות מוצלח. זה לבדו אינו מאשר את ההזמנה.

שניהם משמעותם נסו שוב את אותו תשלום; אל תשלמו הצעה חדשה. הכתובות מזהות ומתעדות את הבעיה; אינן נקודות קצה לתשלום או סקר. נסו שוב POST /api/mpp/booking, והשתמשו ב-type של הבעיה במקום בטקסט החופשי detail כדי להחליט מה לעשות. ראו את הפניה לסוגי בעיות לכל בעיות התשלום של Wink.

פיגור זמן, תגובה אבודה או שגיאת שרת לאחר שליחת התשלום יכולים גם להשאיר את התוצאה לא ידועה. נסו שוב את בקשת התשלום. אם התוצאה נשארת לא ברורה, פנו לתמיכה עם מזהה ההצעה לפני התחלת תשלום נוסף.