المدفوعات الوكيلة

يمكنك البحث عن فندق، اختيار غرفة وإتمام الحجز من خلال وكيل الذكاء الاصطناعي الخاص بك. اربطه بـ Wink ومحفظة دفع، ثم أخبره بالمكان الذي تريد الإقامة فيه. يستخدم Wink بروتوكول المدفوعات الآلية (MPP) لقبول دفع المحفظة وإرجاع تأكيد الحجز الخاص بك.

1. ربط خوادم MCP

لإتمام تدفق الحجز الكامل، يحتاج وكيلك إلى محرك حجز Wink ومحفظة دفع.

الاتصال	ما يفعله	كيفية إضافته
محرك حجز Wink — مطلوب	يعثر على الوجهات، يبحث عن الفنادق وأسعار الغرف، يقدم عروض الأسعار ويؤكد الحجوزات، ويسترجع حجوزاتك وإيصالاتك.	أضف `https://api.wink.travel/mcp/booking-engine` كخادم MCP HTTP عن بُعد.
محفظة الدفع — مطلوبة للدفع	توفر بيانات اعتماد الدفع بعد موافقتك على الشراء.	اربط محفظة تدعم رموز الدفع المشتركة من Stripe. انظر المثال الخاص بـ Link أدناه.
مرجع Wink — اختياري	يبحث عن الدول والعملات وبيانات مرجعية أخرى.	`https://api.wink.travel/mcp/reference`
وثائق Wink — اختياري	تساعد وكيلك على قراءة الوثائق وعقود API.	`https://docs.mcp.wink.travel/mcp`

يتضمن محرك الحجز MCP بالفعل الأدوات اللازمة لتدفق حجز المسافر، عندما يتم تمكين الحجز والدفع الوكيلين لذلك البيئة. MCP الدفع المنفصل من Wink مخصص للعمليات المالية مثل دفاتر الحسابات والسحوبات؛ ولا حاجة له لدفع ثمن الغرفة.

تسجيل الدخول واختيار الأذونات

افتح إعدادات MCP أو الموصل الخاص بوكيلك وأضف عنوان URL لمحرك الحجز أعلاه. امنحه اسمًا مثل Wink Booking.
يفتح وكيلك صفحة تسجيل الدخول إلى Wink في متصفحك. سجّل الدخول باستخدام حساب Wink الذي تريد الحجز من خلاله.
في شاشة الموافقة، اختر الأذونات التي يحتاجها وكيلك، ثم وافق على الاتصال.
عد إلى وكيلك. يقوم بتحميل الأدوات المتاحة ويدير المصادقة لمكالمات MCP التالية.

لهذا التدفق، اختر:

الإذن	سبب الحاجة إليه
وصول وكيل الذكاء الاصطناعي (`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 رمز الدفع المشترك المستخدم لدفع الحجز. تدعم Link حاليًا الحسابات الأمريكية؛ تحقق من حدود الإنفاق قبل الحجز. انظر دليل إعداد Link وتكوين MCP.

إذا كان لدى وكيلك محفظة متوافقة متصلة بالفعل، استخدم ذلك الاتصال. إعداد المحفظة والموافقة على الدفع منفصلان عن تسجيل الدخول إلى Wink.

2. اطلب من وكيلك العثور على غرفة

على سبيل المثال:

ابحث عن غرفة في بانكوك لشخصين بالغين من 15 إلى 17 يناير 2027. أرني الخيارات المتاحة، السعر الإجمالي وشروط الإلغاء قبل أن أختار.

يمكن لوكيلك العثور على حسابات Wink التي يمكنك الوصول إليها وتكوينات الحجز الخاصة بها. إذا كان لديك عدة حسابات، أخبره أيها يستخدم. إذا كنت تحجز عبر رابط حجز أو تكوين مزود، أعطه ذلك للوكيل بدلاً من ذلك.

يقوم الوكيل بعد ذلك بحل وجهتك، يتحقق من الفنادق المتاحة ويحمل أسعار الغرف لتواريخك. اختر غرفة واطلب عرض سعر.

يدعم تدفق الدفع هذا حاليًا غرفة واحدة، مسعرة بالدولار الأمريكي، للبالغين فقط. يحتوي العرض على وقت انتهاء صلاحية. طلب عرض لا يخصم منك أو يؤكد الحجز.

3. راجع ووافق على الدفع

تحقق من الفندق، الغرفة، التواريخ، الضيوف، شروط الإلغاء والمجموع المقتبس. عندما تكون جاهزًا، اطلب من وكيلك الحجز وأكمل أي موافقة يطلبها محفظتك.

توفر المحفظة رمز دفع مشترك من Stripe لدفع العرض.

مدفوعات العملة المستقرة 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`.
الدفع والتأكيد	احصل على رمز دفع مشترك من المحفظة المتصلة، ثم استدعِ `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 المعاد بإمداد رمز دفع مشترك في 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.

يمكن أن يؤدي انتهاء المهلة، فقدان الرد أو خطأ الخادم بعد تقديم الدفع أيضًا إلى ترك النتيجة مجهولة. أعد محاولة نفس طلب الدفع. إذا بقيت النتيجة غير محسومة، اتصل بالدعم مع معرف العرض قبل بدء دفع آخر.