يتم استدعاء عملية الدفع عندما ينشئ المستخدم سلة تسوّق. يتم إرسال محتوى سلة تسوّق المستخدم وتفاصيل الطلب إلى خدمة الويب الشاملة للطلب. تم التحقّق من صحة هذه المعلومات من خلال خدمة الويب، وبعد ذلك يمكنك إما المتابعة أو إجراء تعديلات على سلة التسوق حسب الحاجة.
يجب أن يستجيب معالج الدفع في خدمة الويب إلى طلبات POST. عندما يختار العميل إتمام الدفع، ترسل Google إلى خدمة الويب الشاملة للطلب نص طلب JSON في شكل CheckoutRequestMessage
يحتوي على تفاصيل Cart
الخاصة بالعميل. تستجيب خدمة الويب بعد ذلك لتقديم CheckoutResponseMessage
. ويوضح الرسم البياني التالي هذه العملية.
عند استلام طلب دفع، يجب أن تنفّذ خدمة الويب الشاملة للطلب ما يلي:
- تحقق من صلاحية سلة التسوق بناءً على أسعار العناصر الحالية ومدى توفرها وخدمة المزود.
- احسب السعر الإجمالي (بما في ذلك أي خصومات وضرائب ورسوم التسليم).
- في حال نجاح هذا الإجراء، يمكنك الردّ باستخدام سلة تسوّق غير معدّلة.
- إذا لم تنجح في حل المشكلة، يمكنك الردّ برسالة خطأ وطلب جديد مقترَح.
قبل البدء بتنفيذ عملية الدفع، ننصحك بمراجعة مستندات نظرة عامة على توصيل الطلبات.
رسالة طلب الدفع
للتحقّق من صحّة سلّة التسوّق، عندما يختار العميل إتمام الدفع،
ترسل Google طلبًا إلى خدمة الويب الخاصة بك يتضمّن نص JSON على شكل
CheckoutRequestMessage
. لا يتم تقديم طلب العميل حتى وقت لاحق في
تدفق الطلب من البداية إلى النهاية.
تشمل البيانات الواردة في CheckoutRequestMessage
ما يلي:
- الغرض: يحتوي الحقل
inputs[0].intent
لكل نص طلب دفع على قيمة سلسلةactions.foodordering.intent.CHECKOUT
. - سلة التسوّق: يحتوي الحقل
inputs[0].arguments[0].extension
لطلب الدفع على عنصرCart
يمثّل سلّة التسوّق الخاصة بالعميل. - خدمة التوصيل أو طلب الوجبات الجاهزة لتناولها خارج المطعم: يحتوي حقل الإضافة الخاص بالعنصر
Cart
على عنصرFoodCartExtension
يحدّد خصائص خدمة التوصيل أو الطعام السفري:- بالنسبة إلى طلبات التسليم، يتضمّن العنصر
FoodCartExtension
عنوان التسليم - في ما يتعلق بطلبات الاستلام أو الطعام السفري، لا يحتوي عنصر
FoodCartExtension
على أي معلومات عن الموقع الجغرافي.
- بالنسبة إلى طلبات التسليم، يتضمّن العنصر
- وضع الحماية: يحتوي الحقل
isInSandbox
لطلب الدفع على قيمة منطقية تشير إلى ما إذا كانت المعاملة تستخدم عمليات الدفع في وضع الحماية.
مثال على طلب الدفع
في ما يلي مثال على CheckoutRequestMessage
:
{
"user": {},
"conversation": {
"conversationId": "CTZbZfUlHCybEdcz_5PB3Ttf"
},
"inputs": [
{
"intent": "actions.foodordering.intent.CHECKOUT",
"arguments": [
{
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.Cart",
"merchant": {
"id": "restaurant/Restaurant/QWERTY",
"name": "Tep Tep Chicken Club"
},
"lineItems": [
{
"name": "Spicy Fried Chicken",
"type": "REGULAR",
"id": "299977679",
"quantity": 2,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "AUD",
"units": "39",
"nanos": 600000000
}
},
"offerId": "MenuItemOffer/QWERTY/scheduleId/496/itemId/143",
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P0M"
}
}
},
"location": {
"coordinates": {
"latitude": -33.8376441,
"longitude": 151.0868736
},
"formattedAddress": "Killoola St, 1, Concord West NSW 2138",
"zipCode": "2138",
"city": "Concord West",
"postalAddress": {
"regionCode": "AU",
"postalCode": "2138",
"administrativeArea": "NSW",
"locality": "Concord West",
"addressLines": [
"Killoola St",
"1"
]
}
}
}
}
}
]
}
],
"directActionOnly": true,
"isInSandbox": true
}
رسالة الرد على Checkout
بعد تلقّي طلب من خدمة "الطلب التام بين الأطراف"، يجب أن تعالجه خدمة الويب الخاصة بالدفع على الويب وأن تردّ عليه باستخدام CheckoutResponseMessage
. يجب أن تغطي السمة CheckoutResponseMessage
إما طلب ناجح أو غير ناجح.
تم الطلب بنجاح
إذا تم قبول طلب الدفع، يجب أن يتضمّن CheckoutResponseMessage
كلاً من
ProposedOrder
وPaymentOptions
:
ProposedOrder
cart
: عنصرcart
مطابق لسلة التسوّق المقدّمة فيCheckoutRequestMessage
في حال الحاجة إلى تغيير أي من محتوى سلة التسوّق، يجب أن تتضمّنCheckoutResponseMessage
بدلاً من ذلك عنصرFoodErrorExtension
معProposedOrder
تم تصحيحه.otherItems
: السلع التي يضيفها مقدّم الخدمة، مثل رسوم التسليم والضرائب وغيرها من الرسوم وقد يتضمن أيضًا إكراءً أضافه المستخدم.totalPrice
: السعر الإجمالي للطلبextension
: تحدّد السمةFoodOrderExtension
معلومات تنفيذ الطلب، مثل مدة التسليم.
PaymentOptions
- في مقالة إعداد Google
Pay، ستظهر لاحقًا عملية إعداد معالجة الدفعات.
يمكنك استخدام العنصر النائب JSON في
CheckoutResponseMessage
إلى أن تصبح جاهزًا لتنفيذ عملية معالجة الدفعات. - لإضافة خيارات الدفع النائبة في
CheckoutResponseMessage
، يُرجى الاطّلاع على المثال أدناه، والذي يستخدم نموذجًا لبوابة الدفع فيPaymentOptions
.
- في مقالة إعداد Google
Pay، ستظهر لاحقًا عملية إعداد معالجة الدفعات.
يمكنك استخدام العنصر النائب JSON في
مثال على الاستجابة الناجحة
{
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"checkoutResponse": {
"proposedOrder": {
"cart": {
"merchant": {
"id": "restaurant/Restaurant/QWERTY",
"name": "Tep Tep Chicken Club"
},
"lineItems": [
{
"name": "Spicy Fried Chicken",
"type": "REGULAR",
"id": "299977679",
"quantity": 2,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "AUD",
"units": "39",
"nanos": 600000000
}
},
"offerId": "MenuItemOffer/QWERTY/scheduleId/496/itemId/143",
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P0M"
}
}
},
"location": {
"coordinates": {
"latitude": -33.8376441,
"longitude": 151.0868736
},
"formattedAddress": "Killoola St, 1, Concord West NSW 2138",
"zipCode": "2138",
"city": "Concord West",
"postalAddress": {
"regionCode": "AU",
"postalCode": "2138",
"administrativeArea": "NSW",
"locality": "Concord West",
"addressLines": [
"Killoola St",
"1"
]
}
}
}
},
"totalPrice": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "AUD",
"units": "43",
"nanos": 100000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
"availableFulfillmentOptions": [
{
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P0M"
}
}
}
]
},
"otherItems": [
{
"name": "Delivery fee",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "AUD",
"units": "3",
"nanos": 500000000
}
},
"type": "DELIVERY"
}
]
},
"paymentOptions": {
"googleProvidedOptions": {
"facilitationSpecification": "{\"apiVersion\":2,\"apiVersionMinor\":0,\"merchantInfo\":{\"merchantName\":\"merchantName\"},\"allowedPaymentMethods\":[{\"type\":\"CARD\",\"parameters\":{\"allowedAuthMethods\":[\"PAN_ONLY\"],\"allowedCardNetworks\":[\"VISA\",\"MASTERCARD\"],\"billingAddressRequired\":true,\"cvcRequired\":false},\"tokenizationSpecification\":{\"type\":\"PAYMENT_GATEWAY\",\"parameters\":{\"gatewayMerchantId\":\"YOUR_MERCHANT_ID\",\"gateway\":\"cybersource\"}}}],\"transactionInfo\":{\"currencyCode\":\"AUD\",\"totalPriceStatus\":\"ESTIMATED\",\"totalPrice\":\"43.1\"}} "
}
},
"additionalPaymentOptions": [
{
"actionProvidedOptions": {
"paymentType": "ON_FULFILLMENT",
"displayName": "Pay when you get your food.",
"onFulfillmentPaymentData": {
"supportedPaymentOptions": []
}
}
}
]
}
}
}
]
}
}
}
تعذّرت معالجة الطلب.
في حال لم ينجح طلب الدفع، يجب أن يتضمّن CheckoutResponseMessage
FoodErrorExtension
، الذي يحتوي على قائمة
بعناصر FoodOrderError
التي تصف أي أخطاء حدثت. في حال ظهور أي أخطاء في الطلب يمكن استردادها، مثل تغيير في سعر سلعة في سلة التسوق، يجب أن تتضمّن السمة FoodErrorExtension
correctedProposedOrder
.
مثال على ردّ غير ناجح
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"error": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodErrorExtension",
"foodOrderErrors": [
{
"error": "CLOSED",
"description": "The restaurant is closed."
}
]
}
}
}
]
}
}
}
تنفيذ عملية الدفع
يجب اتّخاذ الخطوات التالية عند تنفيذ عملية الدفع.
التحقُّق من الخدمة
عرض FoodOrderError لحالة خطأ الخدمة الأولى التي تم العثور عليها. هذه الأخطاء غير قابلة للاسترداد، لذا يجب عرض أول خطأ يظهر. يُرجى الاطّلاع على أخطاء المعالجة للحصول على وصف للأخطاء التي يمكن استردادها.
- اقرأ السمة FulfillmentOptionInfo في
الطلب لتحديد ما إذا كان نوع التنفيذ هو
delivery
أوpickup
. عرض أنواع الأخطاء التالية إذا لزم الأمر:
نوع الخطأ حالة الاستخدام INVALID نوع طريقة التنفيذ غير صالح. NOT_FOUND لم يتم العثور على نوع طريقة التنفيذ. مغلقة - لا توجد نوافذ OperationHours للطلب.
- الطلب متاح في أقرب وقت ممكن ولا تتوفّر ServiceHours في الوقت الحالي في أقرب وقت ممكن.
- تم إغلاق الخدمة في حالات الطوارئ أو تم تفعيل الخدمة في
isDisabled
.
UNAVAILABLE_SLOT لا يمكن تنفيذ الطلب المسبَق. NO_CAPACITY المطعم مزدحم ولا يتلقّى الطلبات في الوقت الحالي. OUT_OF_SERVICE_AREA لا يمكن تسليم الطلب إلى عنوان المستخدم. راجع التحقق من عنوان التسليم للحصول على مثال. NO_COURIER_AVAILABLE لا يمكن تسليم الطلب بسبب محدودية موظفي التسليم.
التحقّق من صحة سلة التسوق وتسعيرها
ابحث عن كل سلة تسوّق.
lineItems
وتحقّق من صحتها باستخدام البيانات الحالية في نظامك أو في نظام التاجر. ويتم تضمين القيمة MenuItemOffer.sku
من كيان الخلاصة على أنّها LineItem.offerId
. أنشئ FoodOrderError لكل عنصر إذا لزم الأمر. أنشئ خطأ واحدًا بحد أقصى لكل عنصر. اعرض أنواع الأخطاء التالية إذا لزم الأمر:نوع الخطأ حالة الاستخدام قابلة للاسترداد INVALID بيانات السلع أو أيّ من بيانات الخيارات غير صالحة. لا NOT_FOUND لم يتم العثور على العنصر أو أي من الخيارات. لا PRICE_CHANGED تم تغيير سعر عنصر أو إضافة. يمكن التعامل مع هذا الخطأ على أنه قابل للإصلاح. نعم AVAILABILITY_CHANGED لا يتوفّر المبلغ المطلوب لتفاصيل الإعلان أو أيٍّ من الخيارات. نعم REQUIREMENTS_NOT_MET لم يتم استيفاء الحد الأدنى للطلب أو الحد الأقصى للطلب. يمكن تحديد ذلك من خلال التحقّق مما إذا كان سعر سلة التسوّق أقلّ من الرسوم. eligibleTransactionVolumeMin
أو أعلى من الرسوم.eligibleTransactionVolumeMax
. اطّلِع على المثال في مقالة التحقّق من صحة قيمة طلب الشراء.لا عرض قائمة lineItems التي تم التحقق من صحتها باستخدام LineItemType
REGULAR
. يكون مجموع كل أسعار عناصر سلة التسوق هو سعر سلة التسوق أوSUBTOTAL
.
اطّلِع على أمثلة في عملية التحقق من صحة سلع سلة التسوّق.
حساب رسوم الخدمة
- ابحث عن كيان Fee الصحيح للخدمة استنادًا إلى
eligibleRegion
وvalidFrom
وvalidThrough
وpriority
. - احسب مبلغ الرسوم استنادًا إلى ما إذا تم تحديد الكيان باستخدام السمة
price
أوpercentageOfCart
أوpricePerMeter
. - يمكنك إرجاع رسوم خدمة التوصيل أو طلب الوجبات الجاهزة لتناولها خارج المطعم على أنّها LineItem مع إدخال
LineItemType
DELIVERY
أوFEE
على التوالي. أضف الرسوم إلى قائمة سلة التسوق.otherItems
.
تطبيق الإعلانات الترويجية
- ابحث عن الكيان Deal (الصفقة) استنادًا إلى القيمة المُطابِقة للقيمة
العرض الترويجي.
coupon
مع الصفقة.dealCode
. تأكَّد من صحة الصفقة وأدخِل FoodOrderError إذا لزم الأمر. يمكن التعامل مع هذه الأخطاء على أنها قابلة للإصلاح. اعرض أنواع الأخطاء التالية إذا لزم الأمر:
نوع الخطأ حالة الاستخدام PROMO_NOT_RECOGNIZED لم يتم التعرف على رمز القسيمة. PROMO_EXPIRED انتهت صلاحية الصفقة. PROMO_ORDER_INELIGIBLE الطلب غير مؤهل للحصول على القسيمة. PROMO_NOT_APPLICABLE أي سبب آخر. يمكنك احتساب سعر الصفقة استنادًا إلى الصفقة.
discount
أو الصفقة.discountPercentage
.طبِّق سعر الصفقة باستخدام إجمالي سلة التسوق أو إجمالي الرسوم وفقًا للصفقة.
dealType
.يمكنك إرجاع سلة التسوق.
promotions
مع العرض الترويجي المطبَّق.أعِد العرض الترويجي على شكل LineItem باستخدام LineItemType
DISCOUNT
. أضِف الخصم إلى قائمة سلة التسوق.otherItems
بسعر سلبي.
عرض الرد
- أنشِئ ProposedOrder.
cart
، وستتطابق سلة تسوّق الردّ مع سلة تسوّق الطلب في حال عدم حدوث أيّ أخطاء أثناء التحقّق. - أعِد قائمة ProposedOrder.
otherItems
والتي تشمل الضريبة والرسوم والإكرامية والخصم في حال تطبيقها. راجِع الدرجة غير المجانية للحصول على مزيد من التفاصيل حول كيفية ضبط عنصر الإكرامية. - أدرِج ProposedOrder.
totalPrice
عبر إضافة سعر سلة التسوق والرسوم والخصم والضرائب والإكرامية. - أرسِل السمة
FoodOrderExtension.
availableFulfillmentOptions
مع قيمة FulfillmentOption ذات الصلة. عدِّل الوقت المقدّر للاستلام أو التسليم إلى الوقت المتوقّع - إذا كان هناك FoodOrderErrors تم إنشاؤه من عمليات التحقق السابقة من صحة البيانات:
- أدرِج StructuredResponse.
error
وقائمة الأخطاء في FoodErrorExtension.foodOrderErrors
. - اعرض ProposedOrder في الحقل
correctedProposedOrder
إذا كان من الممكن استرداد جميع الأخطاء. - ارجع إلى PaymentOptions في الحقل
paymentOptions
إذا كان من الممكن استرداد جميع الأخطاء. - اختياريًا، يمكنك تضمين
additionalPaymentOptions
إذا كانت هناك خيارات دفع أخرى متاحة ويمكن استرداد جميع الأخطاء.
- أدرِج StructuredResponse.
- إذا لم تكن هناك أخطاء في عملية التحقّق، اعرض
proposedOrder
،paymentOptions
في العنصر CheckoutResponse. اختياريًا، يمكنك تضمينadditionalPaymentOptions
إذا كانت هناك خيارات دفع أخرى متاحة.